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

# Authentication

## Getting a key

1. Apply at [listed.exchange/partners](https://listed.exchange/partners) with your company, contact, work email, and a short description of what you're building.
2. LISTED reviews each application manually.
3. On approval you're issued one key, shown **once**. It looks like:

```
listed_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

LISTED stores only a SHA-256 hash of it — if you lose it, it can't be recovered, only replaced.

## Using it

Send the key as a bearer token on every request:

```
Authorization: Bearer listed_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```bash
curl "https://listed.exchange/api/v1/quote?from=ETH&to=USDG&amount=1" \
  -H "Authorization: Bearer $LISTED_API_KEY"
```

## Key management

* Each partner gets **one active key at a time**. Ask LISTED to rotate it and the old key is revoked as the new one is issued.
* Keys are **revocable individually** — revoking yours affects no other partner.
* `last_used_at` is refreshed at most once per hour while the key is used. This keeps key-use metadata useful without adding a database write to every request.

## Responses

| Status | Meaning                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `200`  | Authenticated.                                                                                        |
| `401`  | Missing, malformed, or revoked key.                                                                   |
| `429`  | The key exceeded 6,000 requests in 60 seconds. Respect the `Retry-After` header before retrying.      |
| `503`  | The API isn't configured, or the key-validation store is temporarily unavailable. Retry with backoff. |

## Handling

* Keep the key **server-side**. The endpoints have no CORS headers and are not meant to be called from a browser.
* Treat `503` as transient — retry with exponential backoff.
* Treat `401` as terminal — stop and check the key; don't retry in a loop.