> ## 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.

# Autenticação

> API keys, escopos, idempotência e rate limit.

## Bearer token

Toda requisição autenticada leva uma API key:

```
Authorization: Bearer esk_live_xxxxxxxx
```

| Prefixo | Modo | Comportamento |
| - | - | - |
| `esk_test_` | Sandbox | Sem débito de saldo, mensagens simuladas, dados isolados |
| `esk_live_` | Produção | Saldo real, WhatsApp, e-mail e SMS reais |

Crie e revogue chaves em **Configurações → API & Webhooks** no painel.

> [!WARNING]
>
> A chave é exibida uma única vez e dá acesso aos dados da sua organização. Guarde-a em um gerenciador de segredos, nunca em código de frontend ou em repositório.

## Escopos

Chaves novas podem usar `clients:read`, `clients:write`, `debts:read`, `debts:write`, `webhooks:read`, `webhooks:write`, `voice-calls:read` e `voice-calls:write`. Uma requisição fora dos escopos da chave retorna `403`.

Endpoints que não declaram escopo são **exclusivos do painel** e rejeitam API keys com `403`. Isso inclui gestão de chaves, cobrança da plataforma, configurações da organização e a configuração da régua (`/collection`).

## Idempotência

Envie `Idempotency-Key` em `POST` e `PATCH` para que um retry não crie duplicatas:

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

As respostas ficam em cache por 24 horas por chave, organização e endpoint. Reusar a chave com outro payload retorna `409`.

## Rate limit

API keys são limitadas a **100 requisições por minuto** por padrão. As respostas trazem `X-RateLimit-Limit` e `X-RateLimit-Remaining`; um `429` também traz `Retry-After`. O corpo do erro segue a [RFC 9457](https://docs.payable.run/pt-BR/errors.md) com `code` = `RATE_LIMITED`.


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