Authentication and authorisation

Accessing our Demand AP V3 requires a pair of authentication identifiers (Api key token and affiliate id), that you must pass in every request.

Identify the API user in a request

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.

You can authenticate yourself by using both your API key Token and affiliate id header in every request you send to a Demand API endpoint.

• 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.

  

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,
  ...
} '

API key management

An API key is an HTTP bearer token, a cryptic, unique, alphanumeric string that you must pass in every request when using our Demand API.

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 start using our API, you need to generate an API key (Bearer Token) for your API user:

1. Log in to the Affiliate Partner Centre using your partner credentials (username and password).

2. Generate API key token.

3. Copy your API key token and store it securely.

Your API key is now active!🎉

Keep your API key secure

To minimise the risk of misuse of your partner account, you must keep your API keys secure.

Recommendations

The following is a (non-exhaustive) list of best practices that you can use to help you keeping your API key secure.

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:

1. Generate a new API key.
2. Update your client application to use the new API key instead of the old one.
3. 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

To revoke an active API key:

1. Log in to the Affiliate Partner Centre, using your partner credentials (username and password).
2. Revoke the key.

The key is deactivated. Any request to a Demand API endpoint that subsequently tries to use the revoked key will fail with an HTTP 401 status code.

Affiliate ID management

Your first affiliate ID is created automatically when your account is set up and linked to the website you registered. If you need more affiliate IDs (e.g., for multiple websites) you can create these in the Affiliate Partner Centre.

Possible errors

Authentication

When using the API key token and affiliate id for your request, you might find 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.

Access the Affiliate Partner Centre

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.