Using the token-based authentication scheme

Use this approach to authenticate your identity and obtain a token that you can then use to call the Booking.com Connectivity APIs.

When using this method you must first generate an access token and then call the Booking.com Connectivity APIs.

Step 1: Create a machine account

If you do not yet have a machine account using the API token authentication type, you can create one using the Connectivity Portal. Make sure to copy and store the Client ID and Client Secret for later use.

Step 2: Generate an access token

Call the token-based-authentication/exchange endpoint by providing the Client ID and Client Secret for your machine account. The endpoint returns an access token that you can then use to call the Booking.com Connectivity APIs.

The token expires after one hour. You can create up to 30 tokens per hour.

The encoded payload contains the following claims:

Standard claims

• sub: Specifies the subject identifier. For example, sub: connectivity-auth-proxy
• aud: Specifies the intended audience.
• iss: Specifies the issuer who created and signed the token. For example, iss: urn://connectivity-modern-auth/v1.
• exp: Specifies the expiration time (Unix timestamp). For example,exp: 1743761546.
• iat: Specifies the issued at time (Unix timestamp). For example, iat: 1743757946
• jti: Specifies the JWT ID (unique identifier for this token). For example, jti: b9cccca6-14ef-411e-90b7-5c2e0b74b738

Custom claims

• Test: Specifies the intended environment for the token. For example, test: false
• machine_account_id: Specifies the machine account ID. For example, machine_account_id: 10697
• provider_id: Specifies the Provider ID. For example, provider_id: 1507
• client_id: Specifies the Client ID. For example, client_id: 5B5DCB72-7FD4-11EF-B811-E70DD31774E2`

The API supports both XML and JSON formats.

A JSON request example:

POST 'https://connectivity-authentication.booking.com/token-based-authentication/exchange' \
--header 'Content-Type: application/json' \
--data-raw '{
 "client_id": "client_id",
 "client_secret": "client_secret"
}'

An XML request example:

curl --location 'https://connectivity-authentication.booking.com/token-based-authentication/exchange' \
--header 'Content-Type: application/xml' \
--data '<request>
    <client_id>client_id</client_id>
    <client_secret>client_secret</client_secret>
</request>'

A successful response returns an access token.

A JSON response example:

{
    "jwt": "someJWTexampleaXZpdHktYXV0aC1wcm94eSIsImF1ZCI6IiIsInRlc3QiOiJ0cnVlIiwibWFjaGluZV9hY2NvdW50X2lkIjoiOTg1MiIsImlzcyI6InVybjovL2Nvbm5lY3Rpdml0eS1tb2Rlcm4tYXV0aC92MSIsInByb3ZpZGVyX2lkIjoiMTUwNyIsImV4cCI6MTcyNDI1MjMzOSwiaWF0IjoxNzI0MjQ4NzM5LCJjbGllbnRfaWQiOiI3NEM3OTQ5Ni01RkMwLTExRUYtQTg2MC02QjIxQTYxRDZEMDgiLCJqdGkiOiJkOWU3YzU5ZC1mMDVjLTRhOWYtOTM5My1jMTRiNDEyM2U3N2IifQ.r5IhMI-1sRn1SPE4Vf_Txhssl7FS99ZwvX_3fs4y9s10lavcJ8dVQSX93T_T8_R5_v0207JcvlDxiI0VBujD98xG6x6XTkShJTmqyuhOQ6uV2CGwlbRfLSBD3-hIxqWQs-d0BIC9lJxKJui3v6raeq2BGjcC9gmHuYKE5lgM4HlYm682WyaOAaMNAmaTq2EkTH-OfwPzeDq4hu63h4v9UXaIw7IwwbA3WDYyEl3xFfpQBRa__Pyxrrpos9VTku2g7h0IKafBOCUaftzOHUDNXCHgdqqdCkwVk0QMxbzZuUu_WXEcgGoQ3XlZFThyD2xJKoqt0PX7jFvF2oLfp96jaQ",
    "ruid": "XXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

An XML response example:

<response>
    <jwt>"someJWTexampleaXZpdHktYXV0aC1wcm94eSIsImF1ZCI6IiIsInRlc3QiOiJ0cnVlIiwibWFjaGluZV9hY2NvdW50X2lkIjoiOTg1MiIsImlzcyI6InVybjovL2Nvbm5lY3Rpdml0eS1tb2Rlcm4tYXV0aC92MSIsInByb3ZpZGVyX2lkIjoiMTUwNyIsImV4cCI6MTcyNDI1MjMzOSwiaWF0IjoxNzI0MjQ4NzM5LCJjbGllbnRfaWQiOiI3NEM3OTQ5Ni01RkMwLTExRUYtQTg2MC02QjIxQTYxRDZEMDgiLCJqdGkiOiJkOWU3YzU5ZC1mMDVjLTRhOWYtOTM5My1jMTRiNDEyM2U3N2IifQ.r5IhMI-1sRn1SPE4Vf_Txhssl7FS99ZwvX_3fs4y9s10lavcJ8dVQSX93T_T8_R5_v0207JcvlDxiI0VBujD98xG6x6XTkShJTmqyuhOQ6uV2CGwlbRfLSBD3-hIxqWQs-d0BIC9lJxKJui3v6raeq2BGjcC9gmHuYKE5lgM4HlYm682WyaOAaMNAmaTq2EkTH-OfwPzeDq4hu63h4v9UXaIw7IwwbA3WDYyEl3xFfpQBRa__Pyxrrpos9VTku2g7h0IKafBOCUaftzOHUDNXCHgdqqdCkwVk0QMxbzZuUu_WXEcgGoQ3XlZFThyD2xJKoqt0PX7jFvF2oLfp96jaQ"</jwt>
    <ruid>XXXXXXXXXXXXXXXXXXXXXXXXXXX</ruid>
</response>

Step 3: Call the Booking.com Connectivity APIs

Once you have an access token, you can use it to call the Booking.com Connectivity APIs.

A header example:

Authorization: Bearer {JWT}

A request example:

curl --location --request POST 'https://supply-xml.booking.com/hotels/xml/rooms' \
--header 'Authorization: Bearer uhTraWQiOiIxIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJjb25uZWN0aXZpdHktYXV0aC1wcm94eSIsImF1ZCI6IiIsInRlc3QiOiJmYWxzZSIsIm1hY2hpbmVfYWNjb3VudF9pZCI6IjEwNjY1IiwiaXNzIjoidXJuOi8vY29ubmVjdGl2aXR5LW1vZGVybi1hdXRoL3YxIiwicHJvdmlkZXJfaWQiOiIxNTA3IiwiZXhwIjoxNzI3NjkzMTI1LCJpYXQiOjE3Mjc2ODk1MjUsImNsaWVudF9pZCI6IjgxMThFQjRBLTdGMTAtMTFFRi1BQjNDLTY2OTQ2Q0NBMzQ1OCIsImp0aSI6ImY2ZTYwNWM5LWYwZTQtNGQxNy1iYmFiLWUzYmQxODMwOGQ4NyJ9.gnCS-MwgOa..Xx6meTcWkpXzstbV228ji_1KRM5K4wp8pm63hqKZngbgIBw4DVlhf5swct_eja86wDDiXd8LXjM3s-jBwsYGoOtUMa0IPk0gw-bPSrU7rgLl3GaUKirf43g5gqV4WlfwEYBsa_pkRYgveaKMXEEpaar1H0rBYXD9jBgrkOyL8Lf8FBGgKi_JvDolg0RxVxUNQiIuW7RDn5xHxdduwmdOEDHv6LQkcclSn4xyoElAXcOjuh0qS20wTf0Zabb2J3L2h2BuL0gKSdwrFlPLWBQYBXKUSK1fjYKarttqTbDDBK2nXgg26cImHByrkfnMm454BzQMRUTEN-g"' \
--header 'Content-Type: application/xml' \
--data-raw '<request>
  <hotel_id>8135188</hotel_id>
</request>'

Authentication failure

The token expires every one hour. The API returns HTTP 401 for a failed authentication attempt when the token expires. Make sure to refresh the token before it expires by calling the token-based-authentication/exchange endpoint.

A response example when using an expired token:

{
    "code": "401",
    "message": "JWT is wrong or expired, please refresh your JWT."
}

Common errors

This section lists common errors while using the token-based-authentication/exchange endpoint and how to resolve them.

Missing required parameters

Failure to provide a client_id or client_secret parameter in the request body, returns a HTTP 400 response:

{
    "ruid": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "400",
    "error": "Bad Request",
    "message": "client_id and client_secret parameters should exist."
}

Using incorrect Content-Type header

Providing a mismatching Content-Type header can also return a HTTP 400 response.

The following table lists the supported Content-Type header values:

{
    "ruid": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "400",
    "error": "Bad Request",
    "message": "client_id and client_secret parameters should exist."
}

Using invalid API credentials

Providing an invalid or revoked/disabled client_id/client_secret parameter in the request body, returns a HTTP 401 response:

{
    "ruid": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "401",
    "error": "Unauthorized",
    "message": "Invalid or revoked client_id/client_secret."
}

Using incorrect HTTP method

Calling the token-based-authentication/exchange endpoint with a GET or PUT method, returns a HTTP 405 response. Make sure to use the POST method

{
    "ruid": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "405",
    "error": "Method Not Allowed",
    "message": "This endpoint only supports POST requests."
}

Exceeding token generation limit

If you request for more than 30 tokens within an hour, you breach the rate limit and the API returns a HTTP 429 error. Successive HTTP 429 errors can trigger latency.

{
    "ruid": "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "429",
    "error": "Too Many Requests",
    "message": "The rate limit was exceeded for the client_id."
}

FAQs

1. Will migrating machine accounts delete or disable existing or old ones?
No.

2. Is IP allowlisting mandatory?
No, if no IP address is specified, then we won’t filter requests by IP. If one or more IPs are specified instead, the filter will be active and only requests from the listed IPs will be accepted.

3. Is it possible to delete machine accounts?
Only Token based machine accounts can be deleted. A machine account needs to be disabled first before it can be deleted.

4. Can both credential-based authentication and token-based machine accounts be used at the same time?
Yes, you can use both machine accounts until December 31, 2025. On this date, all machine accounts with credential-based authentication will be sunset and will no longer work. Make sure to use the new accounts with the Token-based Authentication method.

5. How can I open the .zip file?
The file cannot be unzipped with the default MacOS app. You can unzip it using Terminal or specialised apps such as The Unarchiver. Windows’ default app can manage the file correctly.

6. What is the rate limit of the endpoint to get tokens?
The rate limit on the exchange end point is 30 per hour. In other words, you can have up to 30 tokens at any point in time. Each token expires 1 hour after the generation.

7. Is the rate limited by IP or machine account?
The exchange API rate limit is limited by machine account.

Related links

-> Authentication best practices