Connecting to the API
The Checkfront API is accessable via a secure authenticated HTTPS connection to our hosted services, and is isolated to your subscription. This requires your application to have the ability to connect to external servers using SSL and one of the identity token services provided to your Checkfront account.
Setting Up Your Application
To start setting up your application, open your Checkfront account page and use the menu to navigate your browser to Manage > Developer. This page will provide access to a listing of your active application clients, as well as containing your webhook notifications configuration under the “Webhooks” tab, and The Developer Console.
Click the “New Application” button in the upper-left corner, and carefully read the terms of service provided.
Choosing Your Workflow
When adding your application, you will be given a choice between two “authentication types”. The method you choose for your application is largely determined by the intended use and scope of your application, and in certain cases you may choose to add more than one access method to your account.
Token Authentication
Token authentication makes use of a simple static private key and secret that can be used for server-to-server communication only. For example, this can be used by an application running on your private web server to create a customer-facing booking page. Applications using this method can only be used privately within your organization, and must not be distributed.
OAuth2 Authentication
OAuth2 is a secure open standard providing a simple transparent avenue of authenticating with the API. Using this method of authentication can allow your application to act on behalf of individual members of your staff by allowing them to “log in” and grant permission to the app. This is ideal for any case where you want to allow your staff to (for example) make or change bookings in the system.
Please see our SDKs or support libraries for OAuth2 in your preferred environment. If we don’t have an example for your language, there are many libraries and documentation available for various programming languages that provide all the functionality you’ll need to implement a custom OAuth2 solution.
Obtaining API Credentials
After you choose an application name (for your own reference), an authentication type, and accept the terms of service, you can click “Create” to save and return to your application listing.
Click on your new application to show the credentials used to connect your application to the API.
Warning
Your API credentials provide your application with access to private data stored on your account and the ability to act on your behalf. Treat these as you would your password, and be careful not to distribute or send these to untrusted parties.
If you are using the SDK, see Setting Up The SDK
Note
Much of the following documentation is intended for custom integrations and understanding of the protocols involved in authentication. Our SDK resources abstract the complex authentication processes to simplify development of your application.
Authenticating with Token Pairs
If you are using token authentication, your application will provide you with two keys:
API Key
Will be set as your HTTP BASIC Username
API Secret
Will be set as your HTTP BASIC Password
When sent together in a request header using HTTP Basic authorization, these allow direct access to API endpoints without any additional preamble.
See CURLOPT_USERPWD if working with cURL libraries, or the documentation on HTTP Basic authentication relevant to your chosen framework. If building your requests manually, HTTP Basic credentials are base64 encoded in the sequence “username:password” and sent in the request header in the following format:
GET /booking/1 HTTP/1.1
Authorization: Basic M2JlOTg2NDFmMDc0NWI2ZmU3ZGFjYzJkZjk0N2FkYmMxZGE3MzEyZDo0YzRkNTk4YTVkOTQwZjA4ZmRiNDM1YjY5YWY5ODZjNzBmMjIwNmRk
Authenticating with OAuth2
Logging in with a Staff Account
Redirect your staff user to your Authorize Token URL (eg.
https://your-company.checkfront.com/oauth/) with the following query string parameters set:client_id
Your application’s “Consumer Key” (see your application setup).
response_type
MUST be set to
coderedirect_uri
The URI to return your user to after authorization.
Upon completion of authorization, the staff user will be sent to the redirect_uri specified, passing a code parameter in the query string that must be exchanged by your application for an access/refresh token pair within 60 seconds.
To exchange the code for an access token, make a call to your Access Token URL (eg.
https://your-company.checkfront.com/oauth/token/) with the following parameters set:client_id
Should be sent as HTTP Basic credentials. See Consumer Key / Consumer Secret.
client_secret
Should be sent as HTTP Basic credentials. See Consumer Key / Consumer Secret.
grant_type
MUST be set to
authorization_codecode
The authorization code as returned in the client’s GET request to your page.
redirect_uri
The URI to return your user to after authorization.
Store the token returned by the previous call in a secure database along with a field containing the timestamp of most recent update to the token. Your tokens should be refreshed on a regular basis as long as the authorization continues to be used.
Your application should store and make use of the following fields from the response:
access_token
string
See Access Token.
expires_in
integer
The time (in seconds) after which the access token will expire.
refresh_token
string
See Refresh Token.
Using and Maintaining OAuth2 Tokens
While your first authentication will provide a usable access token for identifying with the server, the access token has a fixed lifetime and must be refreshed in order to maintain access to the API.
See Refresh Token and other details below for information on performing a refresh.
OAuth2 Reference
Consumer Key / Consumer Secret
These are generated when setting up your application and can be found on your Checkfront developer page. Your consumer key and secret allow your application to grant and refresh tokens on behalf of your users.
Warning
You consumer key and secret should only be sent together when making calls to your Access Token URL. When your application is making calls to endpoints requiring a valid access token, the key/secret pair should not be sent.
As with token pairs (see above), these can (and should) be sent as HTTP Basic credentials. However, these can only be sent in this manner to the /oauth/token/ (code/refresh) endpoint. Your request will be rejected if you attempt to send these to an /api/ endpoint.
See CURLOPT_USERPWD if working with cURL, or the documentation on HTTP Basic authorization relevant to your chosen framework. If building your requests manually, HTTP Basic credentials are base64 encoded in the sequence “username:password” and sent in the request header in the following format:
Authorization: Basic M2JlOTg2NDFmMDc0NWI2ZmU3ZGFjYzJkZjk0N2FkYmMxZGE3MzEyZDo0YzRkNTk4YTVkOTQwZjA4ZmRiNDM1YjY5YWY5ODZjNzBmMjIwNmRk
Access Token
This is used by the API server to identify you and allow the application to act on your behalf. When using OAuth2 for your application, an access token is required to be sent with all API calls to secure data endpoints.
Access tokens have a lifetime of 14000 seconds (this will be returned as expires_in when new tokens are granted), after which they must be refreshed to obtain a new token. Your application should keep track of when this token will be expiring and check if it needs refreshing before attempting a request.
When sending your token with an API request, it can be sent in a header in the following format:
Authorization: BEARER f58ef579d0bb5ffb3b5bb0985a85e21a
It will also be accepted in the form of the query string parameter access_token in the GET request or POST body if necessary for your application, although this is not recommended in a live application.
access_token=f58ef579d0bb5ffb3b5bb0985a85e21a
Refresh Token
After your current access token has expired, this token can be passed to create a new access/refresh token pair, which must completely replace your previously stored token (which will be invalidated).
To exchange the the refresh token for a new access/refresh token pair, make a call to your Access Token URL (eg. https://your-company.checkfront.com/oauth/token/) with the following parameters set:
client_id
Should be sent as HTTP Basic credentials. See Consumer Key / Consumer Secret.
client_secret
Should be sent as HTTP Basic credentials. See Consumer Key / Consumer Secret.
grant_type
MUST be set to
refresh_tokenrefresh_token
The current (active) refresh token for this user.
Refresh tokens have a lifetime of 14 days from issue, after which (if allowed to expire) you must generate a new access/refresh token pair to regain application authorization.
Redirects to new Domain
Checkfront is migrating select customers to our new bookingplatform.app domain to support future features.
When an account is migrated, all requests to your .checkfront.com URL will receive an HTTP 301 redirect response. Browsers automatically follow redirects; redirects for API requests will depend on your HTTP client settings.
HTTP/2 301
location: https://your-company-name.manage.[na1|eu1].bookingplatform.app
In order to continue using the API after being migrated, you need to do one of the following:
Update your API usages to use your new
bookingplatform.appURLEnsure any API usages can handle redirects. This includes redirecting with any necessary authentication information
If using cURL libraries, see the CURLOPT_FOLLOWLOCATION option for following redirects. Set CURLOPT_UNRESTRICTED_AUTH to include authorization headers with the redirect.
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_UNRESTRICTED_AUTH, true);
If you do not wish to automatically redirect with authentication information, conditionally check the original response for an HTTP 301 code. If 301, send a new request to the location provided and include the original authentication information.