The authrocket
Ruby gem works with both Rails and plain Ruby.
There is a streamlined integration available for Rails that provides controllers and helpers. If you are using Rails and prefer to customize the integration, follow the plain Ruby installation instead.
This document covers broad usage of the authrocket
. If you’re just getting started, you may want to read the Quickstart, the Rails Integration Guide, or Ruby Integration Guide first.
If you’ve already been through the Quickstart and have AuthRocket working in your app, you may want to jump down to the General Usage section.
To your Gemfile, add:
gem 'authrocket', '~> 2.0'
To enable the streamlined Rails integration, add this instead:
gem 'authrocket', '~> 2.0', require: 'authrocket/rails'
As always, run bundle
afterward.
If using AuthRocket 1, you must use 1.x or 2.x of the AuthRocket Ruby gem.
By default, AuthRocket automatically loads your credentials from environment variables. For compatible hosting environments, including Heroku, just configure these:
AUTHROCKET_API_KEY = ko_SAMPLE
AUTHROCKET_URL = https://api-e1.authrocket.com/v1
AUTHROCKET_REALM = rl_SAMPLE # optional
AUTHROCKET_JWT_SECRET = jsk_SAMPLE # optional
AUTHROCKET_LOGIN_URL = https://sample.e1.loginrocket.com/ # optional
AUTHROCKET_URL
must be updated based on what cluster your account is provisioned on.
AUTHROCKET_REALM
and AUTHROCKET_JWT_SECRET
are optional. If you’re using a single Realm, it’s easiest to add them here as an application-wide default. If you’re using multiple Realms with your app, we recommend leaving them out here and setting them as you go (it’s easier to debug things this way).
AUTHROCKET_JWT_SECRET
and AUTHROCKET_LOGIN_URL
are both required if using the streamlined Rails integration.
It’s possible to configure AuthRocket using a Rails initializer (or other initialization code) too:
AuthRocket::Api.credentials = {
api_key: 'ko_SAMPLE',
url: 'https://api-e1.authrocket.com/v1',
realm: 'rl_SAMPLE',
jwt_secret: 'jsk_SAMPLE',
loginrocket_url: 'https://sample.e1.loginrocket.com/'
}
Finally, it’s possible to combine several fields into one:
AUTHROCKET_URI = https://ar:ko_SAMPLE@api-e1.authrocket.com/v1
# If using a realm, you can include that too
AUTHROCKET_URI = https://rl_SAMPLE:ko_SAMPLE@api-e1.authrocket.com/v1
# If using JWT for login verification, you'll still need to set AUTHROCKET_JWT_SECRET too.
# Likewise, AUTHROCKET_LOGIN_URL must be set directly as well.
For more details on the headers that these variables are related to, see the API Introduction.
The AuthRocket gem has some similarities to common data libraries like ActiveRecord. It has some differences too.
The gem is ActiveModel compatible, such that it works with standard Rails views and form helpers. Creating and updating records works a little bit differently.
Retrieve all records with AuthRocket::SomeClass.all(params={})
.
users = AuthRocket::User.all realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx'
# => [#<AuthRocket::User ...>, #<AuthRocket::User ...>, ...]
AuthRocket doesn’t use pages of results, as these can change quickly as records are added and deleted. Instead, bulk requests include metadata about if there are more records remaining.
users.more_results?
# => true
To query for more, simply pass the same request with an :after
parameter containing the ID of the last user seen.
more_users = AuthRocket::User.all realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx', after: users.last.id
If you want just the first record, use AuthRocket::SomeClass.first(params={})
. This is effectively the same as calling AuthRocket::SomeClass.all(max_results: 1)
(and supports the same parameters).
user = AuthRocket::User.first realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx'
# => #<AuthRocket::User ...>
Retrieve a single record by its ID. Some resources (such as User) also support an alternate, unique ID; in this case, you may use the two interchangeably.
Two methods are available: AuthRocket::SomeClass.find(id, params={})
and AuthRocket::SomeClass.retrieve(id, params={})
.
find()
will raise an exception if the record cannot be found. retrieve()
will return nil if the record isn’t found.
user = AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
# => #<AuthRocket::User ...>
user = AuthRocket::User.find 'dave'
# => #<AuthRocket::User ...>
Many resources return more fields when queried as a single record (.find
and .retrieve
) than they do when queried in bulk (using .all
or .first
).
Like retrieving a single record, there are two methods for creating records: AuthRocket::SomeClass.create(attribs={})
and AuthRocket::SomeClass.create!(attribs={})
.
user = AuthRocket::User.create invalid: 'data'
# => #<AuthRocket::User ...>
user.valid?
# => false
user.errors?
# => true
user.errors
# => ["Username can't be blank"]
begin
user = AuthRocket::User.create! invalid: 'data'
# => raises AuthRocket::RecordInvalid exception
rescue AuthRocket::RecordInvalid => e
e.object
# => the invalid AuthRocket::User object
end
There are four methods for performing updates on records. The first two operate on an already retrieved record: record.save(new_attribs={})
or record.save!(new_attribs={})
.
user = AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.save first_name: 'Dave', last_name: 'Smith'
# => true (or false, if error)
user = AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.save! first_name: 'Dave', last_name: 'Smith'
# => true (or raises exception, if error)
The other two operate without first retrieving the record. This avoids the API call to retrieve the initial record, so can be twice as fast as retriving and then updating the record: AuthRocket::SomeClass.update(id, new_attribs={})
or AuthRocket::SomeClass.update!(id, new_attribs={})
. Once again, the update!
variant will raise an exception on an error.
user = AuthRocket::User.update 'usr_0v1zUpWdE4IiFc2w5ynShf', username: nil
# => false
user.valid?
# => false
user.errors?
# => true
user.errors
# => ["Username can't be blank"]
user = AuthRocket::User.update! invalid: 'data'
# => raises AuthRocket::RecordInvalid exception
For all methods, only changed attributes need to be sent.
Similar to update()
, there are two methods for deleting records: for use with and without an already retrieved record: record.delete(params={})
and AuthRocket::SomeClass.delete(id, params={})
.
user = AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.delete
# => #<AuthRocket::User ...>
user.errors?
# => false
AuthRocket::User.delete 'usr_0v1zUpWdE4IiFc2w5ynShf'
# => true
If there’s an error, the former will return false and errors will be available in .errors
. The latter will raise a RecordInvalid exception.
Some resources have other resource-specific methods that are outlined in the API docs. Methods that update existing data (instance methods) generally return the same results as .update()
and friends. Methods that operate directly on records (class methods) generally return the same results as .create()
.
Not all resources support all methods. Again, see the API docs.
When using Rails, the some_object.errors
method returns an ActiveModel::Errors
object, providing compatibility with the Rails form helpers. When not using Rails, some_object.errors
will return a simpler structure.
In order to make it possible for .create()
(and certain other methods) to always return an object with a valid .errors
method, those methods do not return false on error. Instead, check new_object.errors?
or use .create!()
.
has_many
, belongs_to
, and associationsIn most cases, the library will transparently handle association relationships for you, similar to ActiveRecord. If the data is already in memory, it is simply returned. If it needs to be loaded, the appropriate call to .all
(has_many type) or .find
(belongs_to type) is handled for you.
realm = AuthRocket::Realm.find 'rl_0v2FcFc5IN79xazvkgLhnX'
# => #<AuthRocket::Realm ...>
realm.users
# => [#<AuthRocket::User ...>, #<AuthRocket::User ...>, ...]
# Same as:
AuthRocket::User.all realm_id: realm.id
realm.users(user_type: 'human')
# Same as:
AuthRocket::User.all realm_id: realm.id, user_type: 'human'
user.realm
# => #<AuthRocket::Realm ...>
# Same as:
AuthRocket::Realm.find user.realm_id
realm.find_user('usr_0v1zUpWdE4IiFc2w5ynShf')
# Same as:
AuthRocket::User.find('usr_0v1zUpWdE4IiFc2w5ynShf', realm_id: realm.id)
realm.create_user(username: 'dave')
# Same as:
AuthRocket::User.create(realm_id: realm.id, username: 'dave')
realm.create_user!(username: 'dave')
# Same as:
AuthRocket::User.create!(realm_id: realm.id, username: 'dave')
realm.update_user('usr_0v1zUpWdE4IiFc2w5ynShf', last_name: 'Smith')
# Same as (except will find it inside any realm unless AUTHROCKET_REALM is set):
AuthRocket::User.update 'usr_0v1zUpWdE4IiFc2w5ynShf', last_name: 'Smith')
realm.update_user!('usr_0v1zUpWdE4IiFc2w5ynShf', last_name: 'Smith')
# Same as (except will find it inside any realm unless AUTHROCKET_REALM is set):
AuthRocket::User.update! 'usr_0v1zUpWdE4IiFc2w5ynShf', last_name: 'Smith')
Realm ->
AppHook ->
Event
AuthProvider ->
Event
Event
LoginPolicy ->
Event
Org ->
Event
Membership
User ->
Credential
Event
Membership
Session
From here we recommend the following:
Questions? Find a Typo? Get in touch.