> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/apis/exchange-api/authentication.md).

# 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 **<support@kumbaya.xyz>** with:

* Your project name and a one-line description
* The endpoints you need
* Expected request volume
* A contact email for revocation/rotation