Configuring the platform for API usage and authentication

Last updated on March 31, 2022

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.

Creating a booking channel

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

Configuring currency usage on the booking channel

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:

  • Display currency
    • You can choose to display prices in any of our supported currencies. This may help the customer get an idea of what the price is in their local currency.
  • Checkout currency (or payment currency)
    • This is the currency that will be used during checkout for creating an invoice and accepting a payment.
    • It is common that websites allow the customer to view prices in many display currencies, but then only support one checkout currency.

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.

Creating an API key

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

 

Authentication and Content-Type headers

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:

  • X-Bokun-Date
    • The date when the request was created in UTC, on the format "yyyy-MM-dd HH:mm:ss".
  • X-Bokun-AccessKey
    • The access key from the API key set.
  • X-Bokun-Signature
    • An HMAC signature created using the secret key from the API key set.

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

  1. Create a string by concatenating the following:
  1. The date as specified in the X-Bokun-Date header.
  1. The access key.
  1. The HTTP method in upper case.
  1. The path (including query string) to the web service being called. Please note, only the path, not the scheme or hostname.
  1. Create a signature with the secret key, taking the concatenated string as input, using the "HmacSHA1" algorithm.
  1. Base64 encode the signature.

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: http://hash.online-convert.com/sha1-generator

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

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

Test sandbox access to API and Swagger UI

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.

  • The API endpoint for the test server is https://api.bokuntest.com.

Rate Limiting

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

  • HTTP response code: 429
  • Retry-After header pointing to a number of seconds this client has to wait until the next call can be made

The above response conforms to RFC 7231, section 7.1.3.

Note that reservation/confirmation calls are excluded from throttling.

Did this answer your question?
😞
😐
🤩