Authentication

Every JSON API request requires authentication. Exchange your API key for a bearer token at POST /auth/token, then send JSON requests with the bearer token:

POST /json/{version}/{endpoint}

Authorization: Bearer <token>
Content-Type: application/json

The auth endpoints are unversioned, so there's no /json/{version} prefix. The same tokens work for the NDC/XML APIs. Submitting an x-api-key header to other endpoints alongside a bearer token is not recommended.

Get an access token

POST /auth/token exchanges your API key for a short-lived bearer token (JWT). It is unversioned and shared by the JSON and NDC/XML APIs.

POST /auth/token

x-api-key: <api-key>
Content-Type: application/json

{ "sellerId": "<seller id>" }

The body is optional. Omit it (or send {}) to get a token for your key's default seller. Send sellerId only when your key can act for more than one seller — see Partner API keys.

Field	Type	Required	Description
sellerId	string (UUID)	No	The seller the token acts as. Must be one of the sellers returned by GET /auth/sellers. Defaults to the key's default seller.

curl -X POST "https://api-staging.flybreeze.com/breeze-offer-order/auth/token" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "sellerId": "3f6c2a9e-8b1d-4c7a-9e2f-5a4b3c2d1e0f" }'

Response — 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
  "token_type": "Bearer",
  "expires_in": 1800
}

expires_in is the token lifetime in seconds. Reuse the token until it expires, then request a new one. The response is not wrapped in the { data, error } envelope.

Each token acts as exactly one seller. Orders, offers, product limits, and webhooks all belong to that seller.

List your sellers

GET /auth/sellers returns every seller your API key can act as.

GET /auth/sellers

x-api-key: <api-key>

curl "https://api-staging.flybreeze.com/breeze-offer-order/auth/sellers" \
  -H "x-api-key: <your-api-key>"

Response — 200 OK

[
  {
    "sellerId": "3f6c2a9e-8b1d-4c7a-9e2f-5a4b3c2d1e0f",
    "sellerCode": "ACM",
    "name": "Acme Travel",
    "isDefault": true
  },
  {
    "sellerId": "b7e1d4c2-6a3f-4e8b-9c1d-2f5a7e9b0c3d",
    "sellerCode": "ACB",
    "name": "Acme Business Travel",
    "isDefault": false
  }
]

Field	Description
sellerId	Seller UUID. Send it as sellerId to POST /auth/token.
sellerCode	Short seller code.
name	Seller display name.
isDefault	true for the seller used when sellerId is omitted. Exactly one seller is the default.

A regular seller key returns a list with just its own seller. Like the token response, this response is not wrapped in the { data, error } envelope.

Partner API keys

Partners that run several sellers, for example multiple agencies or brands, can ask Breeze for a partner API key. A partner key belongs to your partner account and can act as any of that partner's active sellers. Every partner key has a default seller.

To act as a seller, exchange the key for a token with that seller's sellerId. To act as a different seller, exchange the key again with the other sellerId. Tokens are cheap to issue: cache one token per seller and reuse it until it expires.

1. Call GET /auth/sellers to find the sellers your key can act as.
2. Call POST /auth/token with { "sellerId": "…" } for each seller you need.
3. Send each seller's requests with that seller's token.

Which sellerId values a key accepts:

Key type	sellerId omitted	sellerId sent
Partner API key	Default seller	Any active seller of the partner. Other values return 403.
Seller API key	The key's own seller	Only the key's own seller. Other values return 403.

The access level (read-only or full transaction permissions) and request volume limits belong to the key, not to the seller. They apply across all sellers the key acts for, so traffic for every seller counts toward the same key limits.

If you send a partner key directly in the x-api-key header of a non-auth endpoint instead of exchanging it for a token, the request acts as the key's default seller only. Use bearer tokens to act as any other seller.

Auth errors

Code	HTTP status	Cause
ERR-1005	422	Invalid POST /auth/token body, for example a sellerId that is not a UUID.
ERR-8000	401	Missing x-api-key header.
ERR-8001	403	Invalid API key, or the key cannot act as the requested sellerId.
ERR-8002	503	Authentication store unavailable. Retry later.

Response — 403 Forbidden

{
  "message": "The authenticated consumer is not authorized to perform this request.",
  "errorKey": "Forbidden",
  "error": {
    "code": "ERR-8001",
    "title": "Access denied",
    "description": "The authenticated consumer is not authorized to perform this request."
  },
  "requestId": "…"
}

Base URLs

Environment	Base URL
Production	https://api.flybreeze.com/breeze-offer-order
Staging	https://api-staging.flybreeze.com/breeze-offer-order