# Autenticação e chaves de API

Como autenticar na API da SinapsePay com chaves sk_test e sk_live, escopos, IPs permitidos, validade, revogação e limite de requisições.

Toda chamada leva a chave de API no cabeçalho `Authorization`:

```http
Authorization: Bearer sk_live_...
```

A chave é criada no painel, em **Chaves de API**, por quem tem a permissão de gerenciar chaves. O segredo aparece **uma única vez**; a SinapsePay guarda só uma impressão dele e não consegue mostrá-lo de novo. Perdeu? Revogue e crie outra.

## O que define uma chave

| | |
|---|---|
| Ambiente | `sk_test_` (sandbox e Simulador) ou `sk_live_` (produção, depois da aprovação) |
| Produto | PIX Cobrança ou boleto: a chave cria cobranças só do seu produto |
| Integração | Opcional: trava a chave numa integração. Sem ela, vale a integração padrão do produto |
| Escopos | O que a chave pode fazer (abaixo) |
| IPs permitidos | Opcional: só esses endereços conseguem usar a chave |
| Validade | Opcional: a chave para de funcionar na data |

## Escopos

| Escopo | Permite |
|---|---|
| `cobrancas:ler` | Consultar cobranças |
| `cobrancas:criar` | Criar cobranças |
| `cobrancas:cancelar` | Cancelar no banco |
| `cobrancas:baixar` | Dar baixa (pagamento recebido por fora) |
| `cobrancas:devolver` | Devolver PIX recebido (fora da seleção inicial: dinheiro saindo da conta) |

Uma chave nunca pode mais do que a pessoa que a criou. Faltou o escopo: `403 MISSING_SCOPE`.

## Revogação

Revogar vale na hora, para todas as instâncias da API. Alterações de papéis e permissões de quem criou a chave valem em até 10 segundos.

## Limite de requisições

Cada chave faz até **20 requisições por segundo**, com folga para picos de até 40. Acima disso, a resposta é `429` com o cabeçalho `Retry-After` (segundos). Espere esse tempo e repita: com a [`Idempotency-Key`](/docs/idempotencia), repetir é seguro.