Authentication and scopes
Every call carries a tenant token as a bearer token:
Authorization: Bearer <tenant token>
The tenant token
| Property | Value |
|---|---|
| Format | JWT signed with HS256 using the tenant's secret. |
| Tenant binding | The tenantId claim binds the token to one tenant. Every read and write is scoped to that tenant. |
| Purpose | The purpose claim must be supply. A token minted for another Edge surface with the same tenant secret is refused. |
| Role | The role claim. supply_readonly may only call GET, HEAD and OPTIONS; any other value (or none) has read and write access. |
| Actor | The userName, userId or sub claim identifies who is calling. The quote store and repricing record this actor on every write. |
| Expiry | The exp claim. Expired tokens are refused. |
Tokens are issued to an integration during tenant onboarding and are held server-side, for example in the integration layer's secure properties. They are never embedded in a browser or mobile application.
There is no OAuth 2.0 token endpoint (client credentials) for this API, and tokens do not carry per-resource scopes such as orders:write or payments:write. The access levels are the two roles above. See Availability.
The tenant in requests
The token decides the tenant. A request may still send tenantId (query parameter or body field) as a consistency check; if it differs from the token's tenant the request is refused with 403. Examples in this documentation omit it.
Agency and access-scoped tokens
A token can carry an agency_id claim or an access_scope claim (attribute → allowed values). The quote store accepts such tokens and scopes quotes to them. The order orchestration, order operations, group and repricing surfaces refuse them with 403 scope_forbidden, because trips and orders are not partitioned by agency.
For an advisor or agency channel, call these surfaces with the channel's unscoped tenant token and record the agency on the business records: createdBy.kind: agency and agencyRef on the quotation, which conversion carries into the purchase order's attribution.agencyRef.
Agency-partitioned access to trips and orders (an agency token that can only see its own bookings) is not available. See Availability.
Errors
| Status | When | Code |
|---|---|---|
| 401 | No token in production, an invalid or expired token, a token without tenantId, or a token with another purpose. | unauthenticated |
| 403 | tenantId in the request differs from the token's. | forbidden |
| 403 | A supply_readonly token on a write. | forbidden |
| 403 | An agency or access-scoped token on a surface that requires an unscoped token. | scope_forbidden |
Authentication errors carry the standard error envelope (code, message, requestId); see Errors.
Token transport
Send the token in the Authorization header. The service also accepts a token query parameter for browser downloads; do not use it for API integrations, because query strings are written to access logs.