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`

An example request:

POST 'https://connectivity-authentication.booking.com/token-based-authentication/exchange' \
--header 'Content-Type: application/json' \
--data-raw '{
 "client_id": "XXXXXXXX-5FC0-11EF-A860-XXXXXXXXX",
 "client_secret": "someclientsecret"
}'

The response returns an access token.

An example response:

{
    "jwt": "someJWTexampleaXZpdHktYXV0aC1wcm94eSIsImF1ZCI6IiIsInRlc3QiOiJ0cnVlIiwibWFjaGluZV9hY2NvdW50X2lkIjoiOTg1MiIsImlzcyI6InVybjovL2Nvbm5lY3Rpdml0eS1tb2Rlcm4tYXV0aC92MSIsInByb3ZpZGVyX2lkIjoiMTUwNyIsImV4cCI6MTcyNDI1MjMzOSwiaWF0IjoxNzI0MjQ4NzM5LCJjbGllbnRfaWQiOiI3NEM3OTQ5Ni01RkMwLTExRUYtQTg2MC02QjIxQTYxRDZEMDgiLCJqdGkiOiJkOWU3YzU5ZC1mMDVjLTRhOWYtOTM5My1jMTRiNDEyM2U3N2IifQ.r5IhMI-1sRn1SPE4Vf_Txhssl7FS99ZwvX_3fs4y9s10lavcJ8dVQSX93T_T8_R5_v0207JcvlDxiI0VBujD98xG6x6XTkShJTmqyuhOQ6uV2CGwlbRfLSBD3-hIxqWQs-d0BIC9lJxKJui3v6raeq2BGjcC9gmHuYKE5lgM4HlYm682WyaOAaMNAmaTq2EkTH-OfwPzeDq4hu63h4v9UXaIw7IwwbA3WDYyEl3xFfpQBRa__Pyxrrpos9VTku2g7h0IKafBOCUaftzOHUDNXCHgdqqdCkwVk0QMxbzZuUu_WXEcgGoQ3XlZFThyD2xJKoqt0PX7jFvF2oLfp96jaQ",
    "ruid": "980ceb59-2790-7841-b172-57f1c9489653"
}

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.

An example header:

Authorization: Bearer {JWT}

An example request:

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.

An example response when using an expired token:

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

Exceeding token generation limit

If you request for more than 30 tokens within an hour, the API returns a HTTP 429 error.

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