Autenticação

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

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, 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.

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

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.

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)	`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.

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:

{
  "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.

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.

Visão geral

Mensagens

Conversas

Templates

Campanhas

Contatos

Opt-out

Formulários

Automações

Smart Links

Números

Carteira

Consulta de telefone

Recuperação

Conta

Webhooks

Criar a chave

Permissões

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

Rotação e revogação

Erros de autenticação

Próximos passos

Chaves de API

Identidade da chave

​Criar a chave

​Permissões

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

​Rotação e revogação

​Erros de autenticação

​Próximos passos

Chaves de API

Identidade da chave

Criar a chave

Permissões

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

Rotação e revogação

Erros de autenticação

Próximos passos