# Authentication

> API keys, test and live mode, and where keys must (and must never) be kept.

Every request carries an API key:

```http
Authorization: Bearer otp_live_your_key_here
```

The `X-API-Key: <key>` header is accepted too. Keys are created and revoked on the dashboard (**API keys**). A key is shown once, when it is made; OTP.ps keeps only a hash of it.

## Two kinds of key

| Key | Sends messages | Uses credit | Works before approval | Answer includes the code |
|---|---|---|---|---|
| `otp_test_…` (sandbox) | Never | Never | Yes | Yes, as `test_code` |
| `otp_live_…` | Yes | Yes | No | Never |

Test and live are completely separate: a verification made with a test key can't be checked or read with a live key, and the reverse. Limits are counted separately too. See [Sandbox](/docs/sandbox).

## Permissions and daily limits

Each key has permissions (scopes), chosen when you create it:

| Scope | Allows |
|---|---|
| `send` | `POST /api/v1/verify/send` |
| `check` | `POST /api/v1/verify/check` |
| `read` | `GET /api/v1/verify/{id}`, `/balance`, `/usage`, `/limits` |

Give each key only what it needs: a reporting script needs `read` only. Without the needed scope the API answers `403 insufficient_scope`. Keys created before permissions existed have all three.

A key can also have its own **daily message limit**, on top of the account's [spending limits](/docs/security#spending-limits): once reached, that key alone answers `429 spending_limit_reached` until the next day. `GET /api/v1/limits` shows a key's permissions and limits.

## Keep keys on the server

- Put the key in an environment variable (`OTP_PS_API_KEY`) on your backend. Never commit it to Git; add your `.env` file to `.gitignore`.
- **Never** put a key in browser JavaScript, a mobile app, a React/Vue/Next.js client component, or anything the customer downloads. The API sends no CORS headers, so a browser can't call it anyway.
- Your website or app calls **your own** backend (for example `/api/otp/send`), and your backend calls OTP.ps.
- Use separate keys per application, so one can be revoked without stopping the others.
- If a key leaks, revoke it on the dashboard at once and create a new one.

## Errors

A missing, malformed or revoked key answers `401 unauthorized`. A live key on an account that isn't approved yet answers `403 account_pending`. See [Errors](/docs/errors).
