Overview

As part of our ongoing commitment to security enhancements, we are introducing a Token-Based Authentication (OAuth 2.0) solution for the Agoda connectivity system. This new security measure will become the standard for connecting to our Agoda APIs by 2026.

This approach involves obtaining an access token, which acts as a temporary credential for making API requests. This process enhances security by eliminating the need to share or store sensitive credentials during API interactions, making it a preferred choice for modern API integrations.

This flow requires Site Id for your identification and a Client Secret to authenticate your account. Client Secret will be secretly shared with you over your preferred email account.

Step 1: Generate an access token

• To obtain an access token, you need to call the following URL endpoint.
  • URL ENDPOINT: https://{BASE_URL}/identity/v1/token
• In your request, include your Site 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 our APIs. The access token size is expected to remain within 4–8 KB, depending on the token claims.

Example request

curl --location --request POST 'https://{BASE_URL}/identity/v1/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "clientId": "yourSiteID",
  "clientSecret": "yourClientSecret"
}'

Example of successful response

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

Example of failed response

{
    "success": false,
    "responseCode": 2,
    "code": 4,
    "downStreamServiceFailure": false
}

Response codes

• The following table describes the possible responseCode values within the response.

• The following table describes the possible code values within the response.

Step 2: Call our APIs with the access token

• Once you have successfully obtained an access token, you can use it to authenticate your requests to our APIs. Include the token in theX-Auth-Token header of your API calls to access the resources.
• Example: X-Auth-Token: Bearer [jwt]

Example request

curl --location --request POST 'https://{BASE_URL}/{path}' \
--header 'X-Auth-Token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30' \
--header 'Content-Type: application/json' \
--data-raw '{}'

• API responses follow the response structure documented on each API reference page.

Sample failure response

1. JWT is invalid or expired:

{
    "error": {
        "id": 109,
        "message": "Access Token is invalid, expired or missing in the header"
    }
}

OAuth 2.0 Rate Limits

The following rate limits apply only to the access token generation endpoint.

Rate limits by Client ID

Definitions

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

Exceeding rate limits

• Requests beyond allowed limits may be throttled or blocked, and you'll receive a HTTP 429 Too Many Requests response status code.
• To maintain access, implement retry logic with exponential backoff.

Handling Expired Tokens

The access token is valid for one hour. If you attempt to use an expired token, the API will return an HTTP 401 Unauthorized status code. To avoid failed authentication attempts, ensure you refresh the token before it expires by calling the /identity/v1/token endpoint again with your Site 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). For this use case, you can use a remote cache like Redis, DragonflyDB, etc., to save the token for the TTL window.
• If an API call fails with an HTTP 401 Unauthorized error, immediately refresh the token and retry the request.

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

FAQ

Q: How can I get client secret?

1. Your account manager can help you generate Client Secret for you.
2. You will receive two emails:
   • One email containing the password for the Nextcloud link
   • One email containing the Nextcloud link itself
3. Use the provided password to access the Nextcloud link. The client secret will be available there.

Q: I cannot access Nextcloud link.

• The Nextcloud link is valid for 24 hours from the time it is generated. Please make sure to store the client secret in your internal password manager or secrets vault.

Q: How long is the JWT Token validity period.

• Each token is valid for 1 hour. We kindly recommend regenerating the token once every hour and using the same token for all API requests within that hour. This will help reduce unnecessary token traffic and ensure that your requests remain within the allowed rate limits.

Q: When the client secret will be expired?

• The client secret is valid for 1 year after generated (your local time).

Q: How can I get new client secret if the old one expired/lost?

• Your account manager will help you to get new client secret using the same process.
• Once you start using the new client secret that is shared via Nextcloud link please ask your account manager to disable your old client secret for security.

Q: Does Agoda support client secret auto renewal?

• Unfortunately, Agoda does not support this feature yet. Please kindly reach out to us to get the new client secret before the old one expired to avoid disruption to get token.