# Autenticação



## Token de API

Todas as rotas em `/v1/tools/*` exigem um **token de API**, criado no [dashboard](https://dashboard.respawntech.dev) em **APIs**.

| Forma                         | Exemplo                              |
| ----------------------------- | ------------------------------------ |
| Header dedicado (recomendado) | `X-API-Token: rsk_live_...`          |
| Authorization                 | `Authorization: ApiKey rsk_live_...` |
| Authorization (alternativo)   | `Authorization: Token rsk_live_...`  |

<Callout title="Boas práticas">
  Guarde o token na variável de ambiente `RESPAWN_API_TOKEN`, crie um token por integração com os **escopos mínimos** necessários e revogue os que não usar mais.
</Callout>

## Requisitos da conta

Antes de qualquer chamada às ferramentas, a conta precisa ter:

* **E-mail verificado** — caso contrário, `auth.email_not_verified` (403).
* **Saldo não negativo** — conta suspensa retorna `billing.user_bankrupt` (402).
* **Créditos suficientes** — operações pagas sem saldo retornam `billing.insufficient_credits` (402).

## Escopos

Cada rota aceita um conjunto de escopos; basta o token ter **um** deles. Se faltar permissão, a API retorna `scope.missing` (403) com `details.required` e `details.provided`. Os escopos aceitos por cada endpoint aparecem no card do endpoint.

<ScopeTable />

<Callout type="warn" title="PDF é mais restritivo na leitura">
  Rotas de leitura de PDF aceitam apenas `tools:pdf:read` ou `tools:manage`. O escopo genérico `tools:read` e o `tools:pdf:manage` **não** dão acesso à leitura de PDF.
</Callout>

### Combinações recomendadas

| Caso de uso                                  | Escopos sugeridos                                                        |
| -------------------------------------------- | ------------------------------------------------------------------------ |
| Gerar e gerenciar QR codes                   | `tools:qr:dynamic:manage`                                                |
| Painel somente leitura de QRs                | `tools:qr:dynamic:read`                                                  |
| Pipeline de PDF                              | `tools:pdf:manage` + `tools:pdf:read`                                    |
| Verificar URLs antes de exibir               | `tools:safety:read`                                                      |
| Assistente que busca na base de conhecimento | `tools:rag:query`                                                        |
| Enviar e manter documentos da base           | `tools:rag:manage`                                                       |
| [Agente de IA (MCP)](/agentes-de-ia)         | `mcp:use` + os escopos das ferramentas que ele vai usar + `account:read` |
| Integração completa                          | `tools:manage` (mais simples, menos seguro)                              |

## Controles da chave

Além dos escopos, cada token pode ter controles configurados no dashboard. Eles valem em qualquer canal, na API e no [MCP](/agentes-de-ia):

* **Expiração**: depois da data, o token para de funcionar (`auth.unauthorized`).
* **Limite diário de gasto**: uma cobrança que passaria do limite do dia é recusada com `billing.spend_limit_reached` (402), com `details.limit`, `details.spent_today` e `details.required`. O contador zera à meia-noite UTC.
* **Restrição por base de conhecimento**: o token só enxerga as bases escolhidas; as outras respondem `not_found`, e ele não pode criar bases novas (`forbidden`).
* **Modelos prontos**: ao criar a chave, "Somente leitura", "Agente de suporte" e "Agente completo" preenchem escopos e controles de uma vez.

Expiração, limite e bases podem ser alterados depois; os escopos, não. Para mudar escopos, crie outra chave.

## Erros de autenticação

<ErrorTable group="auth" />

## Dashboard vs. token de API

* **Dashboard** — a navegação no painel não consome a franquia diária nem debita leituras medidas.
* **Token de API** — leituras medidas compartilham a [franquia diária](/cobranca-e-limites#franquia-diaria) de <Limit name="dailyQuota" /> requisições (<Limit name="dailyQuotaPremium" /> em contas premium). Depois disso, cada leitura debita créditos.

## Exemplo

Criar um QR com dry-run para validar o token, os escopos e o custo sem debitar nada:

<ApiExamples
  method="POST"
  path="/v1/tools/image/qr-code/dynamic"
  headers={{ 'X-Dry-Run': 'true', 'X-Include-Cost': 'true' }}
  body={`{
"name": "Campanha",
"target_url": "https://example.com"
}`}
/>