AuthRocket for Ruby & Rails

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.

Installation

To your Gemfile, add:

gem 'authrocket'

To enable the streamlined Rails integration, add this instead:

gem 'authrocket', require: 'authrocket/rails'

As always, run bundle afterward.

Configuration

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.

General Usage

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.

Retrieving all records

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

Retrieving the first record

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 ...>

Retrieving a single record

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).

Creating records

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

Updating records

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.

Deleting records

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.

Other methods

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.

Errors

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 associations

In 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')

Associations

Realm ->
    AppHook ->
        Event
    AuthProvider ->
        Event
    Event
    LoginPolicy ->
        Event
    Org ->
        Event
        Membership
    User ->
        Credential
        Event
        Membership
        Session

What’s next

From here we recommend the following:

  • Quickstart - if you haven’t worked through it already
  • API methods - be sure to toggle the examples over to Ruby

Questions? Find a Typo? Get in touch.