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

# Autenticação

> Como enviar a chave de API, restringir permissões, rotacionar e ler os erros de autenticação.

Toda chamada à API leva a chave de API no header `Authorization`.

```bash theme={null}
curl https://api.ararahq.com/auth/me \
  -H "Authorization: Bearer $ARARA_API_KEY"
```

## Criar a chave

Crie, rotacione e revogue chaves em [Chaves de API](https://app.ararahq.com/dashboard/apikeys), no painel. O valor completo aparece uma única vez, na criação. Depois disso o painel mostra só os 4 últimos caracteres.

A chave tem o formato `ara_live_` seguido de 43 caracteres. Toda chave é de produção: a mensagem é entregue de verdade e o custo sai da carteira. Não existe chave de teste.

<Warning>
  Guarde a chave em variável de ambiente ou cofre de segredos. Nunca no código, no frontend ou em URL.
</Warning>

As rotas `/v1/api-keys` não aceitam chave de API: uma chave não gerencia chaves. A resposta é sempre `403`. Chave `ADMIN` recebe `error.code = RESOURCE_FORBIDDEN`; chave com permissões restritas é barrada antes, com o `403` de autenticação, sem `error.code`. Veja [Chaves de API](/api-reference/api-keys).

## Permissões

Chave criada sem escolher permissões tem acesso total (`ADMIN`). Ao restringir, cada permissão libera um conjunto de rotas:

| Permissão | Libera |
| - | - |
| `READ` | `GET` em `/v1/messages`, `/v1/campaigns`, `/v1/templates`, `/v1/flows`, `/v1/charges`, `/v1/automations`, `/v1/numbers` e `/v1/organizations/me/numbers` |
| `MESSAGES_SEND` | Escrita (qualquer método exceto `GET`) em `/v1/messages/**`, `/v1/charges/**`, `POST /v1/media/upload` e `POST /v1/flows/{id}/test` |
| `TEMPLATES_WRITE` | Escrita em `/v1/templates/**` e em `/v1/flows/**` (criar, publicar, desativar e apagar formulário) |
| `CAMPAIGNS_SEND` | Escrita em `/v1/campaigns/**` (inclui estimativa por telefones, cancelamento e A/B) |
| `CONTACTS_WRITE` | Escrita em `/v1/contacts/**` (inclui a remoção LGPD) |
| `WEBHOOKS_MANAGE` | `POST /webhook/cart` (rota legada) |
| `AUTOMATIONS_MANAGE` | Escrita em `/v1/automations/**`. Nunca vem por padrão: peça ao criar a chave. |
| `ADMIN` | Tudo que aceita chave de API |

Todo o resto exige `ADMIN`, inclusive leituras que não estão na linha `READ`: `GET /v1/contacts`, `/v1/conversations`, `/v1/opt-outs`, `/v1/smart-links/whatsapp`, `/dashboard/*`, `/v1/pricing/current`, `/auth/me`.

Para um servidor que só envia, crie uma chave com `MESSAGES_SEND`, mais `READ` se ele consultar status. Uma chave de acesso total também altera recarga automática, perfil comercial e endpoint de recuperação.

Chaves antigas com `scope` continuam valendo: `READ` equivale a `READ`; `SEND` equivale a `READ` + `MESSAGES_SEND` + `CAMPAIGNS_SEND`; `ADMIN` equivale a `ADMIN`.

## Expiração, allowlist de IP e limite diário

Configurados no painel, por chave:

| Restrição | Efeito |
| - | - |
| Expiração (`expiresAt`) | Depois da data, a chave responde `401`. |
| Allowlist de IP | Lista CSV de IPs e faixas CIDR IPv4 (`203.0.113.5,10.0.0.0/8`). Chamada de outro IP responde `401`. Exige plano com trilha de auditoria; sem ele, `403 PLAN_FEATURE_LOCKED`. |
| Limite diário de envio | Teto de mensagens por dia (UTC), de 1 a 1.000.000. Estourou: `429 SEND_RATE_LIMITED`. Campanha consome o número de contatos de uma vez. |

## Rotação e revogação

* **Rotacionar** cria uma chave nova com as mesmas permissões e restrições e revoga a anterior na hora. Não há período de convivência. Para trocar sem parar o serviço, crie uma segunda chave, migre e só então revogue a antiga.
* **Revogar** invalida a chave imediatamente. A próxima chamada responde `401`.

Use uma chave por serviço e revogue quando alguém com acesso sair do time.

## Erros de autenticação

| Situação | Resposta |
| - | - |
| Header `Authorization` ausente | `403` |
| Bearer que não começa com `ara_` | `403` |
| Começa com `ara_` mas não com `ara_live_` | `401` |
| Chave inexistente | `401` |
| Chave revogada | `401` |
| Chave expirada | `401` |
| IP fora da allowlist | `401` |
| Chave válida sem permissão para a rota (veja a tabela em [Permissões](#permissões)) | `403` |
| Rota que não aceita chave de API | `403` |
| Banco de dados indisponível | `503` com `Retry-After: 5` |

Na prática: `401` pede outra chave, `403` pede o header ou outra permissão, `503` pede nova tentativa depois do `Retry-After`.

<Warning>
  Essas respostas não seguem o envelope `{ "error": { "code", "message", "details" } }` do resto da API. O corpo é o JSON padrão do Spring, sem `error.code`:

  ```json theme={null}
  {
    "timestamp": "2026-09-15T14:30:00.000+00:00",
    "status": 401,
    "error": "Unauthorized",
    "path": "/v1/messages"
  }
  ```

  Aqui `error` é uma string. Trate pelo status HTTP antes de ler `error.code`.
</Warning>

Um `403` com `error.code` não é falha de autenticação. É regra de negócio da rota (plano, conta, recurso de outra organização). Veja [Erros](/erros).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Chaves de API" icon="key" href="/api-reference/api-keys">
    Campos da chave e gestão pelo painel.
  </Card>

  <Card title="Identidade da chave" icon="user" href="/api-reference/auth">
    Descubra o usuário e a organização da chave.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.