> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payable.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, scopes, idempotency and rate limits.

## Bearer token

Every authenticated request carries an API key:

```
Authorization: Bearer esk_live_xxxxxxxx
```

| Prefix | Mode | Behavior |
| - | - | - |
| `esk_test_` | Sandbox | No wallet charges, simulated messages, isolated data |
| `esk_live_` | Production | Real balance, real WhatsApp, e-mail and SMS |

Create and revoke keys in **Settings → API & Webhooks** in the dashboard.

> [!WARNING]
>
> Keys are shown once and grant access to your organization's data. Keep them in a secret manager, never in client-side code or a repository.

## Scopes

New keys can use `clients:read`, `clients:write`, `debts:read`, `debts:write`, `webhooks:read`, `webhooks:write`, `voice-calls:read` and `voice-calls:write`. A request outside the key's scopes returns `403`.

Endpoints that do not declare a scope are **dashboard-only** and reject API keys with `403`. This includes key management, billing, organization settings and the collection-flow configuration (`/collection`).

## Idempotency

Send an `Idempotency-Key` on `POST` and `PATCH` so a retry cannot create duplicates:

```
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
```

Responses are cached for 24 hours per key, organization and endpoint. Reusing a key with a different payload returns `409`.

## Rate limits

API keys are limited to **100 requests per minute** by default. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a `429` also carries `Retry-After`. The error body follows [RFC 9457](https://docs.payable.run/errors.md) with `code` set to `RATE_LIMITED`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.