> Section "Authentication" of the AthanLab Developer API documentation (API version 1.0.0). On the web: https://athanlab.com/docs#authentication. Whole documentation as Markdown: https://athanlab.com/docs.md

# Authentication

Send an API key with every request except `GET /openapi.json`.

Request headers:

```sh
X-API-Key: $ATHANLAB_API_KEY
# or
Authorization: Bearer $ATHANLAB_API_KEY
```

For example, this request returns your balance. It needs the `usage:read` scope (see [Scopes](https://athanlab.com/docs#scopes)).

Shell:

```sh
curl -sS https://api.athanlab.com/api/v1/usage \
  -H "X-API-Key: $ATHANLAB_API_KEY"
```

A key is `ak_live_` followed by 32 hex characters. It is shown once, when you create it, so store it in your secret manager.

A missing key returns [401 missing_api_key](https://athanlab.com/docs#errors-missing_api_key). An unknown, malformed, revoked or expired key returns [401 invalid_api_key](https://athanlab.com/docs#errors-invalid_api_key). Unknown and malformed keys also count toward the per-network limit on failed key checks, which blocks a network for 10 minutes with [429 auth_blocked](https://athanlab.com/docs#errors-auth_blocked) (see [Rate limits](https://athanlab.com/docs#rate-limits)).

> [!WARNING]
> **Keep keys on your server**
>
> Never put an API key in a browser, a mobile app or a public repository: anyone who can read it can spend your balance. **If a key leaks**, revoke it in the dashboard at once, or rotate it and choose **Stop the old secret immediately**.

## Scopes

A key can call only the endpoints its scopes allow:

| Scope | Endpoints |
| --- | --- |
| `speech:write` | [POST /speech](https://athanlab.com/docs#endpoint-post-speech), [POST /speech/{id}/cancel](https://athanlab.com/docs#endpoint-post-speech-id-cancel), [POST /deliveries](https://athanlab.com/docs#endpoint-post-deliveries) |
| `speech:read` | [GET /speech](https://athanlab.com/docs#endpoint-get-speech), [GET /speech/{id}](https://athanlab.com/docs#endpoint-get-speech-id), [GET /speech/{id}/audio](https://athanlab.com/docs#endpoint-get-speech-id-audio), [GET /deliveries/{id}](https://athanlab.com/docs#endpoint-get-deliveries-id) |
| `voices:read` | [GET /voices](https://athanlab.com/docs#endpoint-get-voices), [GET /voices/{id}/preview](https://athanlab.com/docs#endpoint-get-voices-id-preview) |
| `usage:read` | [GET /usage](https://athanlab.com/docs#endpoint-get-usage) |

A request outside a key's scopes returns [403 scope_missing](https://athanlab.com/docs#errors-scope_missing).

## Rotate a key

Rotating gives a key a new secret. The 24-hour grace, which keeps the old secret working while you deploy the new one, is for planned rotations only. To end a running grace early, choose **Stop old secret**.