Configuring the platform for API usage and authentication

Before you start using the API, you will need to configure Bokun platform for API access. There are a few things to note here, that we describe in the following sections.

All actions taken on the API must be in the context of a "booking channel". So before you can set up an API key, you should first create a new booking channel. Here are instructions on how to create a booking channel: How to create and use Booking Channels

One important thing to notice when you create a booking channel is the currency settings. The booking channel determines what currency the customer is allowed to use on checkout. We make a distinction between the following:

So, when you edit a booking channel, you must specify what currencies are allowed during checkout and payment. You can choose to either use a single currency, or allow any.

Note: If you allow only one currency, then the checkout API will ignore the currency query parameter and only return values and accept payment in the designated currency specified in the booking channel.

Before you can start using the API, you must set up an API key. Make sure the API key has the permissions needed for the actions you want to take. For instructions on how to do this, please see the following article: How to Create API Keys

The API key consists of an access key and a secret key. You will need to use these keys to create a signature header that authenticates your calls to the API.

The required request headers are:

The X-Bokun-Signature can be created by following these steps:

The web service call will fail if the signature is not correct, or if the date is too far in the past.

Example :

Let's say we are calling the activity search service. We want the results in English and prices in Icelandic Krona (ISK). We have the following:

X-Bokun-Date: 2013-11-09 14:33:46

X-Bokun-AccessKey : de235a6a15c340b6b1e1cb5f3687d04a

Let's say our secret key is 23e2c7da7f7048e5b46f96bc91324800. Now, let's calculate the signature. First select values of the following fields:

Date = 2013-11-09 14:33:46 Access key = de235a6a15c340b6b1e1cb5f3687d04a HTTP method = POST Path = /activity.json/search?lang=EN&currency=ISK

So when concatenating the string (date+accesskey+httpmethod+path) becomes:

2013-11-09 14:33:46de235a6a15c340b6b1e1cb5f3687d04aPOST/activity.json/search?lang=EN&currency=ISK

We then use this, along with the secret key to calculate the HmacSHA1 value for the signature, and Base64 encode it:

X-Bokun-Signature : XrOiTYa9Y34zscnLCsAEh8ieoyo=

The following site can be used for checking your signature:

For POST requests you must also indicate the content type of the post body:

Content-Type: application/json;charset=UTF-8

We can provide test access to the API, loaded with test data. We also provide access to an interactive web console where you can test the API.

Bókun enforces rate limiting on selected endpoints in order to provide adequate quality of service to all its customers. The enforced maximum is 400 requests per minute for the same vendor, regardless of which API key (or set of keys) used. In case if your HTTP client is sending requests at a higher rate than above, the system will respond with the following

The above response conforms to RFC 7231, section 7.1.3.

Note that reservation/confirmation calls are excluded from throttling.