# Authentication

Requests authenticate with an API key in the Authorization header.

Send the key as a bearer token:

`Authorization: Bearer $DISBAND_KEY`

`GET /catalog` is the only route that requires no key.

## Keys

* Create and revoke keys on [API keys](https://disband.io/app/keys) in the web app. An account can have up to 20 keys.
* The secret is shown once, when the key is created, and stored only as a hash. A lost key can't be recovered: revoke it and create a new one.
* The list shows each key's name, its last four characters and when it was last used.
* A key has access to all of the account's separations, including those created in the web app, and spends the account's bought credits. Use keys on servers only, not in browsers or distributed apps.

## Access

| Routes                     | With an API key  |
| -------------------------- | ---------------- |
| `/separations` and below   | Yes              |
| `/usage`, `/usage/history` | Yes              |
| `/catalog`                 | No key required  |
| `/account`, `/keys`        | No, web app only |

Accounts and keys are managed in the web app only, so a leaked key can't create keys or delete the account.

## Credits

Requests with an API key use bought credits only. The free daily credits apply to the web app. Without bought credits, every separation returns [`out-of-credits`](https://disband.io/docs/errors#out-of-credits). See [Credits](https://disband.io/docs/credits).

## Errors

* A missing, malformed, unknown or revoked key returns `401` [`unauthenticated`](https://disband.io/docs/errors#unauthenticated). The response is the same in each case.
* A suspended account returns `403` [`account-suspended`](https://disband.io/docs/errors#account-suspended) for every route except `/usage`.