This Gem enables you to easily connect to the Zaikio Directory and use the OAuth2 flow and easily lookup matching Access Tokens.


Simply add the following in your Gemfile:

gem "zaikio-oauth_client"

Then run bundle install.

Setup & Configuration

1. Setup Active Record encryption

Setup Active Record Encryption by running:

rails db:encryption:init

(Continue generating the credentials each for different environments)

2. Copy & run Migrations

rails zaikio_oauth_client:install:migrations
rails db:migrate

This will create the tables:

  • zaikio_access_tokens

3. Mount routes

Add this to config/routes.rb:

mount Zaikio::OAuthClient::Engine => "/zaikio"

4. Configure Gem

# config/initializers/zaikio_oauth_client.rb
Rails.application.reloader.to_prepare do
  Zaikio::OAuthClient.configure do |config|
    config.environment = :sandbox

    config.register_client :warehouse do |warehouse|
      warehouse.client_id       = "52022d7a-7ba2-41ed-8890-97d88e6472f6"
      warehouse.client_secret   = "ShiKTnHqEf3M8nyHQPyZgbz7"
      warehouse.default_scopes  = %w[directory.person.r]

      warehouse.register_organization_connection do |org|
        org.default_scopes = %w[directory.organization.r]

    config.register_client :warehouse_goods_call_of do |warehouse_goods_call_of|
      warehouse_goods_call_of.client_id       = "12345-7ba2-41ed-8890-97d88e6472f6"
      warehouse_goods_call_of.client_secret   = "secret"
      warehouse_goods_call_of.default_scopes  = %w[directory.person.r]

      warehouse_goods_call_of.register_organization_connection do |org|
        org.default_scopes = %w[directory.organization.r]

    config.around_auth do |access_token, block|
      Zaikio::Hub.with_token(access_token.token) do

To avoid keeping all expired oath and refresh tokens in your database, we recommend to implement their scheduled deletion. We recommend therefore to use a schedule gems such as sidekiq and sidekiq-scheduler.

Simply add the following to your Gemfile:

gem "sidekiq"
gem "sidekiq-scheduler"

Then run bundle install.

Configure sidekiq scheduler in config/sidekiq.yml:

    cron: '0 3 * * *'               # This will delete all expired tokens every day at 3am.
    class: 'Zaikio::CleanupAccessTokensJob'


OAuth Flow

From any point in your application you can start using the Zaikio Hub OAuth2 flow with

redirect_to zaikio_oauth_client.new_session_path
# or
redirect_to zaikio_oauth_client.new_session_path(client_name: 'my_other_client')
# or install as organization
redirect_to zaikio_oauth_client.new_connection_path(client_name: 'my_other_client')

This will redirect the user to the OAuth Authorize endpoint of the Zaikio Directory .../oauth/authorize and include all necessary parameters like your client_id. You may also pass show_signup, force_login and state parameters through, like so:

# Take the user directly to the signup page
redirect_to zaikio_oauth_client.new_session_path(show_signup: true)

# Force the user to re-authenticate even if they have an existing session
redirect_to zaikio_oauth_client.new_session_path(force_login: true)

# Pass a custom Oauth 2.0 state parameter
redirect_to zaikio_oauth_client.new_session_path(state: "something-my-app-uses")

You can also send them to the Subscription Redirect flow, which behaves & redirects back like a regular Organization flow except it additionally sets up a subscription for the organization:

# Require them to select a plan themselves...
redirect_to zaikio_oauth_client.new_subscription_path

# Or preselect a plan for them
redirect_to zaikio_oauth_client.new_subscription_path(plan: "free")

Session handling

The Zaikio gem engine will set a cookie for the access token after a successful OAuth flow: session[:zaikio_access_token_id].

If you are using for example Zaikio::Hub::Models, you can use this snippet to set the current user:

access_token = Zaikio::OAuthClient.find_active_access_token(session[:zaikio_access_token_id])
session[:zaikio_access_token_id] = access_token&.id
Current.user = Zaikio::Hub::Models::Person.find_by(id: access_token&.bearer_id)

unless Current.user
  session[:origin] = request.fullpath
  redirect_to zaikio_oauth_client.new_session_path

You can then use Current.user anywhere.

For logout use: zaikio_oauth_client.session_path, method: :delete or build your own controller for deleting the cookie. If you do build your own controller, please be aware that it is possible for the access token to be nil, and you should handle this accordingly.

Multiple clients

When performing requests against directory APIs, it is important to always provide the correct client in order to use the client credentials flow correctly. Otherwise always the first client will be used. It is recommended to specify an around_action:

class ApplicationController < ActionController::Base
  around_action :with_client


  def with_client
    Zaikio::OAuthClient.with_client Current.client_name do


The zaikio_oauth_client.new_session_path which was used for the first initiation of the OAuth flow, accepts an optional parameter origin which will then be used to redirect the user at the end of a completed & successful OAuth flow.

Additionally you can also specify your own redirect handlers in your ApplicationController:

class ApplicationController < ActionController::Base
  def after_approve_path_for(access_token, origin)
    session[:zaikio_person_id] = access_token.bearer_id unless access_token.organization?

    # Sync data on login
    Zaikio::Hub.with_token(access_token.token) do
      access_token.bearer_klass.find_and_reload!(access_token.bearer_id, includes: :all)

    origin || main_app.root_path

  def after_destroy_path_for(access_token_id)


  def error_path_for(error_code, description: nil)
    # Handle error

Custom behavior

Since the built in SessionsController and ConnectionsController are inheriting from the main app's ApplicationController all behaviour will be added there, too. In some cases you might want to explicitly skip a before_action or add custom before_action callbacks.

You can achieve this by adding a custom controller name to your configuration:

# app/controllers/sessions_controller.rb
class SessionsController < Zaikio::OAuthClient::SessionsController
  skip_before_action :redirect_unless_authenticated

# config/initializers/zaikio_oauth_client.rb
Zaikio::OAuthClient.configure do |config|
  # ...
  config.sessions_controller_name = "sessions"
  # config.connections_controller_name = "connections"
  # ...


You can use our test helper to login different users:

# test_helper.rb
class ActiveSupport::TestCase
  # ...
  include Zaikio::OAuthClient::TestHelper
  # ...

# my_controller_test.rb
class MyControllerTest < ActionDispatch::IntegrationTest
  test "does request" do
    person = people(:my_person)

    # ... make the request

For system tests (e.g. with a separate browser instance), there's a special helper:

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  include Zaikio::OAuthClient::SystemTestHelper

  test "does request" do
    person = people(:my_person)

    visit "/"

Authenticated requests

Now further requests to the Directory API or to other Zaikio APIs should be made. For this purpose the OAuthClient provides a helper method with_auth that automatically fetches an access token from the database, requests a refresh token or creates a new access token via client credentials flow.

Zaikio::OAuthClient.with_auth(bearer_type: "Organization", bearer_id: "fd61f5f5-038b-44cf-b554-dfe9555f1e29", scopes: %w[directory.organization.r directory.organization_members.r]) do |access_token|
  # call config.around_auth with given access token

If you need the token for a certain period (e.g. a long-running job which makes many requests in sequence), you can specify the valid_for interval when requesting the token. By default, it won't return an access token which was due to expire in less than 30 seconds from now. If there is an existing token, but it was due to expire before the end of the validity period, this will go and get a fresh token anyway:

Zaikio::OAuthClient.with_auth(..., valid_for: 10.minutes) do |access_token|
  # ...

Use of dummy app

You can use the included dummy app as a showcase for the workflow and to adjust your own application. To set up the dummy application properly, go into test/dummy and use puma-dev like this:

puma-dev link -n 'zaikio-oauth-client'

This will make the dummy app available at: http://zaikio-oauth-client.test

If you use the provided OAuth credentials from above and test this against the Sandbox, everything should work as the redirect URLs for http://zaikio-oauth-client.test are approved within the Sandbox.


Make sure you have the dummy app running locally to validate your changes.

  • Make your changes and submit a pull request for them
  • Make sure to update

To release a new version of the gem:

  • Update the version in lib/zaikio/oauth_client/version.rb
  • Update to include the new version and its release date
  • Commit and push your changes
  • Create a new release on GitHub
  • CircleCI will build the Gem package and push it Rubygems for you


The gem is available as open source under the terms of the MIT License.