Step 1: Generate Your Client ID and Client Secret

To connect to the Agoda.com Connectivity APIs with OAuth 2.0 authentication, you need a Client ID and Client Secret. These credentials are required to authenticate your application and generate an access token.

To get your credentials, please go to please go to API access management in YCS page and follow the instruction on the page.

Step 2: Generate an access token

To obtain an access token, you need to call the following URL endpoint:

URL ENDPOINT: https://supply.agoda.com/token-based-authentication/exchange

In your request, include your Client ID and Client Secret to authenticate your account. The endpoint will respond with an access token, which you must include in the headers of your subsequent API requests to access the Agoda.com Connectivity APIs.

Example Request

POST 'https://supply.agoda.com/token-based-authentication/exchange' \
--header 'Content-Type: application/json' \
--data-raw '{
 "clientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX",
 "clientSecret": "yourclientsecret"
}'

Example Successful Response

{
    "success": true,
    "responseCode": 1,
    "code": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30",
    "downStreamServiceFailure": false
}

Example Failed Response

{
    "success": false,
    "responseCode": 60,
    "code": 20,
    "downStreamServiceFailure": false
}

Step 3: Call the Agoda.com Connectivity APIs

Once you have successfully obtained an access token, you can use it to authenticate your requests to the Agoda.com Connectivity APIs. Include the token in the Authorization header of your API calls to access the resources.

Authorization: Bearer [jwt]

!! Please also make sure that you have removed API Key URL parameter !!

Example Request

curl --location --request POST 'https://supply.agoda.com/{path}' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30' \
--header 'Content-Type: application/xml' \
--data-raw '<request>
  <hotel_id>8135188</hotel_id>
</request>'

Rate Limits

Rate Limits by Client ID

Rate Limits by IP Address

Definitions

• Total Attempts : Total number of API requests, regardless of outcome (success/fail).
• Successful Calls : Requests that result in a successful response (e.g., HTTP 200).

What Happens If You Exceed Limits?

• Requests beyond allowed limits may be throttled or blocked.
• To maintain access Implement retry logic and exponential backoff.

Authentication failure

The access token is valid for one hour. If you attempt to use an expired token, the API will return an HTTP 403 Forbidden status code. To avoid failed authentication attempts, ensure you refresh the token before it expires by calling the https://supply.agoda.com/token-based-authentication/exchange endpoint again with your Client ID and Client Secret.

Best Practice: Token Refresh Logic

To ensure uninterrupted API access, implement a mechanism in your application to refresh the token proactively. For example:

• Capture the current system time and store it alongside the token.
• Schedule a token refresh shortly before it expires (e.g., 5 minutes earlier).
• If an API call fails with an HTTP 403 error, immediately refresh the token and retry the request.

By handling token expiration gracefully, you can maintain seamless interactions with the Agoda.com Connectivity APIs.

Response Codes

The following code is for the responseCode within the response: