Skip to content

Authentication

All API integrations authenticate using a Client Account API key passed via the X-API-Key header. This is the only supported authentication method for server-to-server integrations.

Client Account API Key

A Client Account is a named service credential created by your tenant admin. It is entirely separate from user accounts — there is no email, password, or login flow. Think of it as a named API credential for a specific integration.

A Client Account encapsulates:

  • A unique API key (rn_<base64url>, 46 chars)
  • A configurable per-minute request limit (MaxRPM)
  • Access to specific supplier accounts and filter profiles
  • Association with a client organisation and tenant

Getting your API key

Your tenant admin creates a Client Account for your integration. The raw API key is shown only once at creation time — store it immediately in a secure secrets manager. If the key is lost, the admin can rotate it via rollApiKey.

Using the API key

Include the key in the X-API-Key header on every GraphQL request:

POST /graphql HTTP/1.1
X-API-Key: rn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{"query": "{ checkHotels(input: { ... }) { hotels { ... } } }"}

Keys start with rn_ followed by 43 characters of base64url-encoded random bytes. They are stored server-side as SHA-256 hashes — the plaintext key is never retained after creation.

Client Account API keys have access to the hotel booking operations: checkHotels, checkRate, bookRate, cancelBooking, amendBooking, checkBooking, and booking.

Keep API keys secret

Do not commit API keys to source control, include them in client-side code, or log them. If a key is exposed, ask your tenant admin to roll it immediately.

Rate limiting

Requests authenticated with an API key are rate-limited per Client Account based on the configured MaxRPM value. Exceeding the limit returns HTTP 429 Too Many Requests with a Retry-After: 60 header.

JWT bearer token (frontend / UI only)

JWT bearer tokens issued by the login mutation are used by the RateNet frontend application and are not the intended mechanism for programmatic API integrations.

Note

If you are building a custom frontend or UI on top of RateNet and need user-level authentication (email + password, session management, role-based UI access), use the login mutation to obtain a JWT and pass it as Authorization: Bearer <token>. For all other integrations, use a Client Account API key.

Error responses

An errors entry with "UNAUTHENTICATED" code indicates a missing or invalid credential. A 403 Forbidden / "FORBIDDEN" code indicates the credential is valid but lacks access to that operation.