Authentication & scopes

API keys

Send your key on every request (except GET /health):

Authorization: Bearer wk_live_ab12cd34_0123456789abcdef0123456789abcdef0123456789abcdef

or, if you cannot set the Authorization header:

X-API-Key: wk_live_ab12cd34_0123456789abcdef0123456789abcdef0123456789abcdef

Key format: wk_<environment>_<8 hex prefix>_<48 hex secret>

Part	Meaning
`live`	Real bookings are created
`test`	Sandbox: bookings are simulated and not persisted (see Sandbox)
prefix	Identifies the key in your console, usage logs and audit trail. Safe to log
secret	Never logged. Only a SHA-256 hash is stored on our side, so we cannot recover it

Treat keys like passwords. Keep them server-side; never embed them in mobile apps or browser code. If a key leaks, ask the platform administrator to revoke it (immediate) and issue a new one.

Scopes

A key can only call what its scopes allow. A missing scope returns 403 insufficient_scope.

Scope	Allows
`search:read`	`POST /search/flights`, `/search/hotels`, `/search/cars`
`pricing:read`	`GET /pricing/quote`
`bookings:read`	`GET /bookings`, `GET /bookings/{id}`
`bookings:write`	`POST /bookings`, `POST /bookings/{id}/cancel`
`invoices:read`	`GET /invoices`, `GET /invoices/{id}`
`webhooks:manage`	`POST /webhooks`, `GET /webhooks`, `DELETE /webhooks/{id}`

The platform administrator can also disable a scope for every client at once (403 scope_disabled) or switch the whole API off (503 api_disabled).

Tenant isolation

A key acts for one API client, which is linked to one tenant. You can only ever read:

bookings created by your client,
invoices belonging to your tenant,
webhook endpoints registered by your client.

Requesting anything else returns 404, never another organisation's data.

Optional protections

IP allow-list — a key can be restricted to specific IPs or CIDR ranges (403 from other addresses).
Expiry — a key can expire automatically (401 afterwards).
Request signing — clients can be required to HMAC-sign every write request. See Request signing.

Suspension and revocation

Situation	Response
Key revoked or expired	`401 unauthorized`
Client suspended	`403 forbidden`
API switched off by the administrator	`503 api_disabled`

Checking a key

GET /me returns the client, environment, whether a tenant is linked, and the scopes on the key — a quick way to validate a newly issued key.