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

# Autenticação

> Como a chave de API identifica a organização, e os limites de cada chave.

Cada chamada leva a chave de API da organização no cabeçalho `Authorization`:

```text theme={null}
Authorization: Bearer qx_sua_chave
```

## A chave

* A chave começa com `qx_`.
* A chave pertence a uma organização. A chamada alcança só os dados dessa organização.
* O admin do QX cria a chave e entrega o texto da chave por um link de uso único. O texto aparece uma vez só.
* Guarde a chave no gerenciador de segredos do seu servidor.
* Nunca envie a chave por e-mail, e nunca grave a chave em log.
* Se a chave vazar, peça ao QX a revogação. A próxima chamada com a chave revogada recebe `401`.

## As recusas

A API confere a chave e a organização antes de cada chamada.

| Status | `code`                  | Quando                                      |
| ------ | ----------------------- | ------------------------------------------- |
| 401    | `unauthorized`          | A chave falta, não existe ou está revogada. |
| 402    | `subscription_blocked`  | A assinatura da organização está bloqueada. |
| 403    | `organization_archived` | A organização está arquivada.               |
| 403    | `plan_required`         | O plano gratuito não inclui a API.          |

## Os limites

Uma escrita paga é uma chamada que dispara um serviço pago, como a consulta de um CNPJ ou a leitura de um documento. As escritas pagas são estas:

* `POST /contacts`;
* `POST /collections`;
* `POST /documents`;
* `PATCH /documents/{id}` com `file`.

| Limite                             | Valor          | `code` do `429`         |
| ---------------------------------- | -------------- | ----------------------- |
| Chamadas de uma chave              | 300 por minuto | `rate_limited`          |
| Escritas pagas de uma chave        | 30 por minuto  | `rate_limited`          |
| Escritas pagas de uma chave        | 1.000 por dia  | `daily_limit_reached`   |
| Chaves inválidas de um endereço IP | 60 por minuto  | `too_many_invalid_keys` |

* O dia do limite diário segue o fuso da organização. O limite volta à meia-noite.
* Cada resposta `429` traz o cabeçalho `Retry-After`, com os segundos de espera.
* O QX ajusta o limite diário de uma chave a pedido da organização.