The BookingSync API uses OAuth 2.0 for authorization.
OAuth2 is a protocol that lets external apps request authorization to private details in a user’s BookingSync account without getting their password.
All applications that want to use the API must be registered on the BookingSync website.
Each registered application is assigned a unique Client ID and Client Secret. It is important that the Client Secret is not shared with anyone and not accessible by users.
For testing the authorization process in console or play around the API, refer to Testing BookingSync Authorization
When building applications that are meant to be embedded in the BookingSync App Center, keep in mind that the authorization redirect can’t be done with a simple 301 redirect.
The BookingSync website serves the X-Frame-Options: DENY header, which
prevents it from being embedded in any iframe. Therefore, browsers won’t be
able to show the authorization prompt within an iframe.
Instead, embedded applications must use javascript to redirect to the auth screen:
<script type='text/javascript'>
window.top.location.href = 'https://www.bookingsync.com/oauth/authorize';
</script>Scopes let the application request access to a subset of the API. Requested scopes are displayed to the user with the authorization prompt.
By default, all requests include the public scope, which allows readonly
access to public information.
Additionally, the following scopes are available:
applications_readbookings_write_ownedbookings_readbookings_writeclients_readclients_writeinbox_readinbox_writeinquiries_write_ownedinquiries_readinquiries_writepayments_write_ownedpayments_readpayments_writepreferences_general_settings_readpreferences_general_settings_writepreferences_payments_readpreferences_payments_writerates_readrates_writerentals_readrentals_writereviews_readreviews_writewebhooks_readwebhooks_writewebhooks_write_ownedNote: To request authorization for multiple scopes, use a space separated list.
In URLs it would look like &scope=bookings_read%20rentals_read (%20 represent a space within URLs)
Application can also use the
OAuth 2.0 Authorization Code flow
to access the API.
This is to be used for Server-Side applications, with special care taken to never leak client_secret.
This authorization process is required only once. When your first set of tokens received, you will no longer need this process unless an account intentionnally uninstalled your application. The refresh token process will then be used.
For more details, visit our Testing BookingSync Authorization page for a step by step guide.
The explicit OAuth 2.0 flow consists of the following steps:
https://www.bookingsync.com/oauth/authorize, with these query string parameters
* client_id
* redirect_uri - must be under an apps registered domain
* response_type - must be code
* scope - options (details)
* state - optional
* account_id - optional, used to force which account will be requested to authorize more details
https://www.bookingsync.com/oauth/token
* client_id
* client_secret
* code - from the previous step
* grant_type - must use authorization_code
* redirect_uri - must be the same as the provided in the first stepThis request is responded to with either an error (HTTP status code 401) or the following sample request:
{
"access_token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
"scope": "public"
}
API calls made with expired access_token will return an HTTP Status Code 401 (Unauthorized).
To prevent this from happening, you can request a new access_token using the refresh_token as demonstrated below before the access_token expiration.
You can find your token lifetime (in seconds), by checking the expires_in attribute in authorization response.
A refresh token is valid as long as it's used (or your application is uninstalled), therefore you can also request a new set of tokens after expiration of your access_token.
A new refresh_token will be generated after each refresh, therefore make sure to save it.
As the refresh token gives you lifelong access to an account, it must be stored securely.
For more details, visit our Testing BookingSync Authorization page for a step by step guide.
https://www.bookingsync.com/oauth/token
* client_id
* client_secret
* refresh_token - from above section, step 4 response
* grant_type - must use refresh_token
* redirect_uri - must be the same as the provided in the first stepThis request responds with either an error (HTTP status code 401) or the following sample request:
{
"access_token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
"scope": "public"
}
Application can also use the OAuth 2.0 Implicit flow to access the API. This is recommended for Client-Side applications.
The implicit OAuth 2.0 flow consists of the following steps:
https://www.bookingsync.com/oauth/authorize, with these query string parameters
* client_id
* redirect_uri - must be under an apps registered domain
* response_type - must be token
* scope (details)
* state - optional
* account_id - optional, used to force which account will be requested to authorize more details
Once you have authenticated a user once, regardless of flow, subsequent re-authorizations will occur without requiring user action. Naturally, should a user revoke an applications permissions then further action will be required to re-authorize.
Application can also use the OAuth 2.0 Client Credentials flow to access the API.
This is useful for bulk access, for example in a rental listing application. Instead of iterating over each authorized Account and fetching their rentals, the application can use the Client Credentials flow and fetch all rentals at once.
You still need each account to be authorize your application by using the Authorization Code Flow.
Requests using a token obtained using the Client Credentials flow are limited to using only the public scope, but can access most of the resources of BookingSync Accounts that authorized the given Application as long as the access is not limited by other OAuth scopes.
The client credentials OAuth 2.0 flow consists of this single step:
https://www.bookingsync.com/oauth/token
* client_id
* client_secret
* grant_type - must use client_credentials
This request responds with either an error (HTTP status code 401) or the following sample request:
{
"access_token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"token_type": "bearer",
"expires_in": 7200,
"scope": "public",
"created_at": 1466671142
}
When the token used to authorize the request is invalid, expired or revoke, the API will return a 401 response. When the token is valid, but doesn’t have the scopes necessary to perform requested action, the API will return a 403 response.
When calling your Admin URL, we pass the parameter _bookingsync_account_id. The value of this parameter can be used as the account_id parameter during the authorization process. Doing so will pre-select the account to authorize when using the Authorization Code Flow or Implicit Flow.