Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Code Climate Build Status

BookingSync Engine


This engine requires Rails >= 5.0.0 and Ruby >= 2.3.0.


API documentation is available at


BookingSync Engine works with Rails 4.2 onwards and Ruby 2.2 onwards. To get started, add it to your Gemfile with:

gem 'bookingsync-engine'

Then bundle install:

bundle install

Then mount BookingSync Authorization routes inside routes.rb:

mount BookingSync::Engine => '/'

This will add the following routes:

  • /auth/bookingsync/callback
  • /auth/failure
  • /signout

BookingSync Engine uses the Account model to authenticate each BookingSync Account, if you do not have an Account model yet, create one:

rails g model Account

For single application setup

Then, generate a migration to add OAuth fields for the Account class:

rails g migration AddOAuthFieldsToAccounts provider:string synced_id:integer:index \
  name:string oauth_access_token:string oauth_refresh_token:string \

and migrate:

rake db:migrate

Also include BookingSync::Engine::Models::Account in your Account model:

class Account < ActiveRecord::Base
  include BookingSync::Engine::Models::Account

For multi application setup

Then, generate a migration to add OAuth fields for the Account class:

rails g migration AddOAuthFieldsToAccounts provider:string synced_id:integer:index \
  name:string oauth_access_token:string oauth_refresh_token:string \
  oauth_expires_at:string  host:string:uniq:index

Add manually null: false to the host field on the newly created migration file, then migrate:

rake db:migrate

Also include BookingSync::Engine::Models::MultiApplicationsAccount in your Account model:

class Account < ActiveRecord::Base
  include BookingSync::Engine::Models::MultiApplicationsAccount

You also need to create applications

rails g model Application

Then, generate a migration to add credentials fields for the Application class:

rails g migration AddCredentialsFieldsToApplications host:string:uniq:index client_id:text:uniq:index \

Add null: false to this 3 attributes, then migrate:

rake db:migrate

Also include BookingSync::Engine::Models::Application in your Application model:

class Application < ActiveRecord::Base
  include BookingSync::Engine::Models::Application

Activate the multi app mode in an initializer:

BookingSyncEngine.setup do |setup|
  setup.support_multi_applications = true

Use different models for single app and multiple app setup

To make transition between the two modes on the fly, you can use different model name for your accounts.

For the following example:

class MySingleAppAccount < ActiveRecord::Base
  include BookingSync::Engine::Models::Account

class MyMultiAppAccount < ActiveRecord::Base
  include BookingSync::Engine::Models::MultiApplicationsAccount

You just need to define which model goes with which mode in an initializer.

BookingSyncEngine.setup do |setup|
  setup.single_app_model = -> { ::MySingleAppAccount }
  setup.multi_app_model = -> { ::MyMultiAppAccount }


The engine is configured by the following ENV variables:

  • BOOKINGSYNC_URL - the url of the website, should be
  • BOOKINGSYNC_APP_ID - BookingSync Application's Client ID
  • BOOKINGSYNC_APP_SECRET - BookingSync Application's Client Secret
  • BOOKINGSYNC_VERIFY_SSL - Verify SSL (available only in development or test). Default to false
  • BOOKINGSYNC_SCOPE - Space separated list of required scopes. Defaults to nil, which means the public scope.

You might want to use dotenv-rails to make ENV variables management easy. See spec/dummy/.env.sample.

Embedded vs Standalone apps

The engine is set up by default to work with Embedded app for the BookingSync app store. This means that the OAuth flow will redirect using javascript redirect to break out of the iframe.

Embedded apps

Embedded apps will need to allow BookingSync to load them in an iframe.

This only has to be applied to the part of the application used in BookingSync

You can use the following helper in your controller to do just that:

after_action :allow_bookingsync_iframe

Standalone apps

Standalone applications will be working outside of BookingSync website. While it's not the recommended approach, some applications can benefit from this.

To make your application standalone, you must set the standalone mode by adding the following code to an initializer:


Authentication in apps

BookingSync Engine will create some helpers to use inside your controllers and views.

Ensure authentication

To set up a controller with BookingSync account authentication, just add this before_action:

before_action :authenticate_account!

It will make sure an account is authenticated (using OAuth2).

New authorization process

If the user is not currently authenticated, 3 responses can be expected:

1) Through Ajax requests

By Ajax request, we consider them when the X-Requested-With header contains XMLHttpRequest.

In this case, the authorization path will be returned a plain text with a 401 Unauthorized status.

2) Embedded Application

Embedded applications will be given a script tag forcing them to change their parent location to the authorization path. This is necessary so the authorization happens in the main window, not within an iFrame.

3) Standalone Application

Standalone applications will simply be redirected to the authorization path.

Accessing the current account

To retrieve the current signed-in account, this helper is available:


Securing applications

Session cookies

You should make sure session cookies for you application have the secure flag. This will be done by Rails automatically if you have configured your environment with config.force_ssl = true. If not, you can change your session_store.rb initializer:

Rails.application.config.session_store :cookie_store,
  key: '_your-app_session', secure: true


We would love to see you contributing. Please, just follow the guidelines from


By default, your tests will run against the Rails version used in the main Gemfile.lock, to test against all supported Rails version, please run the tests with Appraisals with: appraisal rake spec

Testing with docker

You can choose to run PostgreSQL in a Docker container. At the moment, you should use Beta channel on a Mac - so you can reach the docker machine on localhost. It is possible to set it up with stable, but then you have to configure it another way.

Use spec/dummy/config/database.yml.docker instead of spec/dummy/config/database.yml.

Once intalled, setup the DB with docker-compose create, docker-compose start and rake db:setup


Kickstart your BookingSync Application with this Rails 5+ Engine







No packages published