Authentication
OAuth 2.0 client credentials, machine to machine. Tokens are short-lived JWTs scoped to your organization and roles; send Authorization: Bearer <token> on every request and mint fresh tokens rather than caching near expiry.
| Scope | Grants |
|---|---|
catalog:read | Browse catalogs, avails, and rates within your agreements |
catalog:write | Sellers: publish packages, rates, avails |
orders:write | Create, confirm, respond, cancel |
orders:approve | Sellers: decide orders at the review gate |
webhooks:manage | Register and allowlist notify endpoints |
settlement:read | Invoices and make-good ledger on cleared trades |
Webhooks the platform sends you carry an HMAC signature in X-Signature computed over the timestamp and body; verify it with your signing key before trusting any event, and reject stale timestamps. Tokens are validated for audience: a token minted for another service will be rejected here.
Acting-buyer identity
A single credential can act for several buyer organisations: an agency group, a holding company's desks, or a platform placing orders on behalf of its own customers. The acting buyer is buyer_entity, and it appears on every order, every read, and the seller's tenant roster.
The token decides it, not the request. buyer_entity is a projection of the token's subject, minted by RFC 8693 token exchange where sub is the buyer being acted for and act.sub names the platform doing the acting. You do not have to send it: omit it and the platform fills it in from your credential.
Sending it is allowed, and it is an assertion rather than an instruction. It is compared against the tenant the credential resolves to:
| You send | Result |
|---|---|
| Nothing | The platform fills in the resolved tenant. The ordinary case. |
The matching buyer_entity | Accepted, and identical to having sent nothing. |
A different buyer_entity | 403 TENANT_MISMATCH. Nothing is created. |
The mismatch is refused rather than ignored on purpose. Booking under the resolved tenant while you asserted another would let one buyer's order be recorded against a sibling's name, and that surfaces as a commercial dispute at invoice time instead of an authentication error at request time. A buyer_entity also never travels in a URL path, so a tenant identifier never lands in an access log or a cache key.
Sellers see the acting buyer on every order and can suspend one without disturbing the others on the same connection: see Tenant roster and tenant_policy.mode on the capability_profile.