Authentication

The recommended mechanism is OAuth 2.0 with the client_credentials grant. You exchange a client_id + client_secret for a short-lived bearer token and send that token on every API call. HTTP Basic and API-key credentials are also offered for callers that cannot run a token exchange.

OAuth 2.0 client-credentials flow

1. Request a token

Send a form-encoded POST to the token endpoint, on the same host and /api/v1 prefix as every other call:

curl -s -X POST \
  https://ari.console.adrasis.com/api/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'

Request fields (all form-encoded, application/x-www-form-urlencoded):

Your client library may instead send client_id and client_secret as HTTP Basic credentials, as RFC 6749 section 2.3.1 describes: Authorization: Basic followed by the base64 of client_id:client_secret, each form-encoded first. The body then carries only grant_type and, if you want it, scope. Use one of the two ways on a request, not both: a request with both answers invalid_request.

curl -s -X POST \
  https://ari.console.adrasis.com/api/v1/oauth/token \
  -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  -d 'grant_type=client_credentials'

2. Read the response

A successful exchange returns 200 OK:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "distribution:read distribution:booking",
  "issued_at": 1748851200
}

A failed exchange returns a standard OAuth error envelope:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed.",
  "requested_scope": null
}

3. Send the bearer token

Attach the token to the Authorization header on every Distribution call:

curl -s \
  https://ari.console.adrasis.com/api/v1/properties \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

The token carries your partner-account identity and granted scopes. The service verifies both the token and its live credential/account binding on every request. There is no session or tenant header to send.

Partner account and profile selection

A credential always authenticates one partner account. Credentials are owned by the account, not by an individual profile, so you do not need a different credential for each catalogue audience.

Profile-scoped REST operations accept this optional header:

X-Adrasis-Partner-Profile-Id: <16-character-profile-public-id>

Omit the header on the first request to select the account's stable Default profile. Send it to select another profile owned by the same account. Every successful profile-scoped response returns the exact identity used:

X-Adrasis-Resolved-Partner-Profile-Id: <16-character-profile-public-id>

Persist opaque cursors, selection proofs, and prebook tokens unchanged. Each one seals the profile that created it, so a continuation can restore that profile without the header. If you repeat the header, it must match the sealed identity. Unknown or cross-account profiles return 404; inactive explicit profiles return 403; a temporarily unavailable profile resolver returns retryable 503.

GET /bookings is the reporting exception. It is account-wide and accepts profile_public_id as an optional query filter for the immutable originating profile, including a profile disabled after booking. It does not use the profile-selector header.

4. Handle expiry

Tokens are valid for expires_in seconds (3600). No refresh token is issued for the client-credentials grant. When a token expires, request a new one from the token endpoint with the same client_id / client_secret.

A missing, malformed, expired, or signature-invalid token returns 401 with a WWW-Authenticate: Bearer challenge header and one of these codes. The same three codes cover the Basic and API-key mechanisms below, so a client that handles them once handles every mechanism:

{
  "error": {
    "code": "CREDENTIAL_UNAUTHORIZED",
    "message": "Credential is missing, invalid or revoked",
    "trace_id": "01J8ZC4M2P6QK5R7T9VXA3B1DN",
    "retryable": false
  }
}

Every Distribution endpoint uses UPPER_SNAKE codes inside the standard error envelope described in Errors. The token exchange in step 2 is the one exception: it returns the OAuth error envelope above, as its own specification requires. Branch on code; the message is human-readable and may change between releases.

CREDENTIAL_UNAUTHORIZED is deliberately one code rather than several. Which verification step failed is not disclosed, so an attacker cannot use the error body to distinguish "this client exists but the secret is wrong" from "this client does not exist". Treat all three as "obtain a fresh credential or token and retry"; none of them is worth an automatic retry with the same input.

A practical strategy is to cache one token in memory and refresh it slightly before expires_in elapses (for example, at ~90% of the window) rather than requesting a token per call.

Scopes

Two scopes gate the surface. A token must carry the scope an endpoint requires, or the request returns 403 with code: INSUFFICIENT_SCOPE.

A read-only integration only needs distribution:read. That covers both the bulk and single-property accommodation searches, availability check, and the content feed. The vertical search endpoints (/transfer/search, /tour/search, /flight/search, /package/search) sit under distribution:booking. A full booking integration needs both scopes. Use the scope request parameter to down-scope a token when a worker only needs a subset (for example, mint a read-only token for a search service even though the credential is granted both).

Alternative mechanisms

The seller can also issue, from Connectivity > Sales channels > API partners in its Console, HTTP Basic and API-key credentials for callers that cannot run a token exchange. Unlike OAuth, these do not use the token endpoint. The credential material is sent directly on each call (Basic on the Authorization: Basic header; an API key with the adr_ prefix as Authorization: Bearer adr_...). They are gated by the same distribution:read and distribution:booking scopes. OAuth 2.0 is recommended for new integrations because tokens are short-lived and the long-term secret never travels on data requests.

Next steps

• Getting started: Make the first authenticated call.
• The booking flow: Review the endpoints these scopes gate.
• Booking webhooks: Configure signed push notifications.
• Errors: See the full status-code reference.