# Autenticação

Toda requisição à API da Quyta exige um **token de API** enviado no header
`Authorization`, no formato Bearer:

```bash
curl https://app.quyta.com.br/api/v1/debts \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
```

Não há login, refresh token nem fluxo OAuth: o token é gerado no painel da Quyta e usado
diretamente.

## Headers de conteúdo

A API **sempre responde JSON**, inclusive nos erros. Você não precisa negociar formato:
não há `Accept` obrigatório, e um `GET` só precisa do `Authorization`.

```bash
curl "https://app.quyta.com.br/api/v1/debts" \
  -H "Authorization: Bearer $QUYTA_TOKEN"
```

O único header de conteúdo que importa é o **`Content-Type: application/json` em `POST` e
`PUT`** — e por um motivo funcional, não de formato de resposta: sem ele o servidor não
interpreta o corpo como JSON, lê os campos como vazios e devolve 422 em tudo.

| Requisição | Header necessário |
| --- | --- |
| `GET`, `DELETE` | nenhum além do `Authorization` |
| `POST`, `PUT` | `Content-Type: application/json` |

## Como obter um token

Os tokens são criados no painel da Quyta, na área de configurações de API. Ao criar um
token você define:

1. **A conta** a que ele pertence — o token só enxerga os dados dessa unidade.
2. **As permissões** que ele carrega (veja a tabela abaixo).
3. **A validade**, se o token deve expirar.

:::danger
O token é exibido **uma única vez**, no momento da criação. A Quyta guarda apenas um hash —
não é possível recuperá-lo depois. Se você o perder, revogue e gere outro.
:::

## Onde guardar

O token dá acesso de escrita à sua carteira. Trate-o como senha:

- guarde em variável de ambiente ou cofre de segredos, nunca no código-fonte;
- nunca o exponha em front-end, aplicativo móvel ou log;
- use tokens distintos por ambiente e por sistema integrado — assim revogar um não derruba
  os outros;
- revogue imediatamente qualquer token que possa ter vazado.

## Permissões

Cada endpoint exige uma permissão específica. Um token só consegue chamar aquilo que lhe
foi concedido — conceda o mínimo necessário.

| Permissão | Libera |
| --- | --- |
| `customers.list` | `GET /customers` |
| `customers.show` | `GET /customers/{id}` |
| `customers.create` | `POST /customers` e `PUT /customers/{id}` |
| `customers.update` | Telefones e e-mails: `POST` e `DELETE` em `/customers/.../phones` e `/emails` |
| `debts.list` | `GET /debts` |
| `debts.show` | `GET /debts/{id}` |
| `debts.create` | `POST /debts` |
| `debts.update` | `PUT /debts/{id}` |
| `debtgroups.list` | `GET /debtgroups` |
| `debtgroups.show` | `GET /debtgroups/{id}` |

Um exemplo prático: uma rotina noturna que só envia carteira precisa de
`customers.create`, `debts.create` e `debtgroups.list`. Um painel interno que apenas
consulta situação precisa somente das permissões `*.list` e `*.show`.

:::note
`PUT /customers/{id}` é coberto por `customers.create`, e não por `customers.update`.
A permissão `customers.update` governa apenas a manutenção de telefones e e-mails.
:::

## Erros de autenticação

Todos seguem o mesmo formato de resposta:

```json
{
  "message": "Token não encontrado",
  "error_code": "API_AUT_02",
  "status_code": 401
}
```

| `error_code` | HTTP | O que aconteceu | O que fazer |
| --- | --- | --- | --- |
| `API_AUT_01` | 401 | Header `Authorization` ausente ou malformado. | Envie `Authorization: Bearer {token}`. |
| `API_AUT_02` | 401 | Token não existe. | Confira se copiou o token inteiro e se está no ambiente certo. |
| `API_AUT_03` | 401 | Token expirado. | Gere um novo token no painel. |
| `API_AUT_04` | 401 | Token revogado. | Gere um novo token. Se você não o revogou, avise o time de segurança. |
| `API_AUT_05` | 403 | Token válido, mas sem a permissão exigida. | Conceda a permissão no painel ou use um token adequado. |

A diferença entre **401** e **403** importa no seu tratamento de erros: 401 significa
"esse token não serve" — repetir a requisição não adianta. 403 significa "esse token é
válido, mas não pode fazer isso" — é um problema de configuração, não de credencial.

## Limite de requisições

A API aceita **1.000 requisições por minuto** por token. Ao ultrapassar esse limite as
requisições passam a responder `429 Too Many Requests`.

Para cargas grandes, veja as recomendações em
[Sincronizando a carteira](/guias/sincronizacao#respeitando-o-limite-de-requisições).