Authentication and authorisation

Accessing our Demand AP V3 requires a pair of authentication identifiers, that you must pass in every request.

Overview

Every request to a Demand API endpoint (in both production and sandbox) must identify the API user that is sending the request.

Each API user has an unique pair of identifiers (your partner id and one of your affiliate ids) that allows access to Version 3 of the Demand API (sandbox and production).
Your partner account is configured with at least one API user.

To enable an API user to access the Demand API, you must do the following:

Generate an API key for your partner account.

An API key expires after 12 months. You should generate another one after this period. You can also replace or revoke it if needed before that.

Use your API key and the appropriate affiliate id to authenticate the calling API user in every request you send to a Demand API endpoint.

Identify the API user in a request

Whenever you call a Demand API endpoint, you must identify the calling API user by including both of the following headers in the request:

Authorization: Bearer <key>
where <key> is your active API key value.
X-Affiliate-id: <aid>
where <aid> is the affiliate id for the API user that you want to use to make the request.

Make sure your request uses HTTPS, to ensure secure transmission of the bearer token. If you send the request over an unsecured (HTTP) connection, it will not work.

An example (with dummy values) of how to use these headers in a request.

curl --request POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search' \
--header 'X-Affiliate-Id: 123456'\
--header 'Authorization: Bearer xyz.........xyz'\
...
--data-raw '{  
  "city": -2140479,
  ...
} '

Possible errors

A request may fail with the following HTTP status codes:

401 - The specified API user is invalid.
403 - The specified API user is authenticated, but does not have permission to access the requested endpoint.

For more information on how to deal with these errors, see Error handling.

API key management

An API key is an HTTP bearer token - a unique, cryptic, alphanumeric string. Using bearer tokens for authentication provides a high level of security and means you do not have to use your partner credentials to access the API.

Generate an API key

To generate an API key for an API user:

Note

If you are unable to access the Affiliate Partner Centre, this could be due to one of the following reasons:

Partner centre not enabled: If the Partner Centre is not enabled for your account, you will need to contact your Booking.com account manager. Your account manager can enable access for you, allowing you to use the Affiliate Partner Centre.
User access issues: If you personally do not have access to the Partner Centre, it's possible that another member of your organization has the necessary credentials. Identify who in your organization has access to the Partner Centre and request them to add you as a user. For guidance on managing users in your account, refer to this support article.

Once these access issues are resolved, proceed with generating your API key.

Generate the new key.
Copy the new API key and store it securely.

Attention

For security reasons, this is the only time the API key will be displayed in full. If you do not copy the key now, or subsequently lose the key, you cannot recover it and will have to replace it.

The new API key is now active.

Keep your API keys secure

To minimise the risk of misuse of your partner account, you must keep your API keys secure. The following is a (non-exhaustive) list of best practices that you can use to help you do this.

Store an API key securely:

Don't store the key directly in your application's source code. Store the key separately in an environment variable, which you can reference from your application when needed.
Don't store an unencrypted key in a source control system repository - public or private.
Consider using a secrets management service to store and manage your API keys.

Actively control access to and maintain an API key:

Only share the key with another user if they definitely need it. Make sure that the sharing user is aware of their security responsibilities for the key.
Replace the key on a regular basis - at least once a year.
If you suspect that the key has been compromised, revoke it immediately and then generate a new one.
Revoke the key if you no longer need it.

Replace an API key

Your affiliate partner account can have a maximum of two active API keys at any time. This allows you to replace a key without having to take the application out of service.

To replace an API key:

Generate a new API key.
Update your client application to use the new API key instead of the old one.
When you are confident that all application requests are working properly with the new key, and that the old one is no longer being used anywhere, revoke the old key.

Revoke an active API key