Authentication and Authorization
Overview
To access the API, your metasearch product must have a registered active account and use an associated API key. The API key should be kept secret and used only to obtain an access token, which can then be used to send requests to the API endpoints.
If you don't have a registered active account or an API key, contact your account manager.
Authentication credentials
| API key | Access token | |
|---|---|---|
| Purpose | For obtaining an access token | For sending in HTTP headers of API requests |
| Target | /auth | Any endpoint except /auth |
| Lifetime | Long term | Short term |
| Expiration | Doesn't expire | Expires after a short time |
| Secrecy | High | Low |
Once created, the API key does not have an expiration date. It remains active and ready for use unless revoked. It must be kept secret and should not be shared with unauthorized persons or via open communication channels. If compromised, contact your account manager to generate a new API key.
Obtaining an access token
Before querying a Connect API endpoint, you must obtain an access token by authenticating with the API key. To do this, call the /auth endpoint and pass the API key as a form parameter api_key, for example:
curl -X POST --location 'https://metasearch-connect-api.booking.com/auth' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'api_key=abc...xyz'
Ensure that the request uses HTTPS to secure the transmission of the API token. Do not send the request over an unsecured HTTP connection.
If the request succeeds, it will return a JSON response body containing an access token in the access_token field:
{ "success": "true", "access_token": "CAES...", "expires_in": "28800" }
Extract the access token and keep it ready to include in the requests. Note that the response will also contain the number of seconds until the token expires. During this time, the same token can be reused.
Make an authorized request
In every request to the Connect API endpoints, add a Bearer Authorization HTTP header using the following format ( replace YOUR_ACCESS_TOKEN with the access token obtained earlier):
Authorization: Bearer YOUR_ACCESS_TOKEN
An example (with dummy values) of how to use these headers in a request:
curl --location 'https://metasearch-connect-api.booking.com/accommodations/details' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer CAES...' \ --data '{ "accommodations" : [ 0000000 ], "accommodation_facilities" : [ 0000000 ], "accommodation_types" : [ 0000000 ], "rows" : 2, "extras" : [ "rooms", "payment", "description"] }'
Possible errors
A request may fail with the following HTTP status codes:
- 400 - The specified API key is invalid.
- 401 - The corresponding API account is not active.
- 403 - The specified API user is authenticated but does not have permission to access the requested endpoint or a specific option of the endpoint.
For more information on how to deal with these errors, see Error handling.
API key management
To minimize the risk of misuse of your account, you must keep your API keys secure. Here is a (non-exhaustive) list of best practices for doing so:
Store an API key securely:
- Do not store the key directly in your application's source code. Instead, use an environment variable for storage, which your application can access when needed.
- Avoid storing an unencrypted key in any source control system repository, public or private.
- Consider utilizing a secrets management service for storing and managing your API keys.
Actively control access to and maintain an API key:
- Only share the key with users who absolutely need it, ensuring they are aware of their security responsibilities.
- If you suspect the key has been compromised, immediately contact your account manager for a replacement.