# Autenticação

Toda chamada à API leva uma chave no cabeçalho:

```
Authorization: Bearer sk_live_...
X-Tenant-Id: <o id da sua loja>
```

A chave é criada no painel, em **Integração**. Ela aparece **uma vez** — no
momento em que é gerada. Guarde-a onde guarda as suas outras credenciais; se a
perder, revogue e crie outra. Não temos como a recuperar, e isso é de propósito:
uma chave que pode ser pedida de volta acaba em capturas de ecrã e bilhetes de
suporte.

## A chave é da loja, não da pessoa

Se quem a criou sair da empresa, a chave continua a funcionar e continua
revogável por quem ficou. É essa a diferença entre uma chave de API e o acesso
de alguém ao painel.

O painel mostra **quem a emitiu** e **quando foi usada pela última vez**. Uma
chave sem uso há meses é uma chave a mais para vazar — revogue-a.

## O que ela pode fazer

Uma chave de API cobre a operação: criar cobranças, consultar, estornar. **Não
cobre** gerir a equipa, mexer nas credenciais dos adquirentes nem ler a trilha
de auditoria. Isso exige uma pessoa autenticada no painel, com o papel para tal.

A separação é deliberada: uma chave que possa tudo transforma qualquer fuga num
incidente total.

## Erros que vai encontrar

| Estado | O que significa |
|---|---|
| `401` | A chave falta, está errada ou foi revogada |
| `403` | A chave é válida mas não tem permissão para esta operação |
| `404` | O recurso não existe **ou não é da sua loja** — não distinguimos os dois de propósito |
| `429` | Excedeu o limite de chamadas; ver `Retry-After` |

O `404` em vez de `403` para recurso de outra loja é intencional: dizer "existe,
mas não é seu" já conta quem existe do outro lado.