Authentication

The Exchange API has two auth tiers: public read endpoints, and partner-keyed quote endpoints.

1. Public (no auth)

Most read-only endpoints - health, status, pools, tokens, stats, and user positions - work with no credentials. They're rate-limited per IP. Note: the quote endpoints are not public; they all require a partner API key (see below).

2. Partner API key

All four quote endpoints require a partner API key: GET /api/v1/quote, POST /api/v1/quote, POST /api/v1/quote/open, and GET /api/v1/quote/tokens. Request a partner API key from the Kumbaya integrations team.

• Header: x-api-key: <YOUR_KEY> by default. (The header name is configurable server-side via the PARTNER_API_KEY_HEADER env var; production uses the default.)

• Keys are per-partner and rate-limited.

• Failed validation returns 401 { "error": "Invalid API key" }.

• If no partner keys are configured server-side at all, the partner-key guard becomes a no-op - useful for local dev.

Don't pass the partner key as Authorization: Bearer …. That header is reserved for JWT-based auth on other Kumbaya APIs (e.g. the Client API).

Allowlist-off quotes

POST /api/v1/quote/open uses the same partner API key as the other quote endpoints, but with the token allowlist disabled - it quotes any pair. It is not origin-restricted; a valid x-api-key is all it needs.

Getting a key

Email [e-mail] with:

• Your project name and a one-line description

• The endpoints you need

• Expected request volume

• A contact email for revocation/rotation