In an HTTP request for all Agoda APIs, authentication headers are mandatory. If omitted, the API will return the error message, based on authentication method provided in the API. These authentication methods provide a secure and standardised way to authenticate your identity and interact with the Agoda.com APIs.

Supported Authentication methods:

OAuth 2.0
API Key

OAuth 2.0 (Recommended)

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 Agoda.com APIs.

Example Request

POST 'https://{BASE_URL}/identity/v1/token' \
--header 'Content-Type: application/json' \
--data-raw '{
 "clientId": "yourSiteID",
 "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 2: 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 APIs. Include the token in theX-Auth-Token header of your API calls to access the resources.

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/xml' \
--data-raw '{}'

Successful response with X-Auth-Token header to maintain same structure as shared in API references.

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

Rate limiting configuration below is valid only for generating access token API.

Rate Limits by Client ID

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

Response Codes

The following code is for the responseCode within the response:

API-Key

Every request must include an Authorization Header with your siteid and apikey, separated by a colon. This must match the siteid and apikey in the request body. The Authorization header is mandatory for all API requests.

Authorization Header Format:

Authorization: <Site-ID>:<API-Key>

Example Authorization header:

Authorization: 123456:00000000-0000-0000-0000-000000000000

Your account manager will share the API Key with you.

Example Request

curl --location --request POST 'https://{BASE_URL}/{path}' \
--header 'Authorization: 123456:00000000-0000-0000-0000-000000000000' \
--header 'Content-Type: application/xml' \
--data-raw '{}'

Successful response with Authorization header to maintain same structure as shared in API references.

Sample Failed Response

1. Missing Headers

{
    "error": {
        "id": 108,
        "message": "Site ID or API key is invalid or missing in the header"
    }
}

2. Incorrect Site ID

{
    "error": {
        "id": 101,
        "message": "Site ID 123456 is invalid"
    }
}

3. Incorrect API Key

{
    "error": {
        "id": 102,
        "message": "API key *****d11eb is invalid"
    }
}

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.