AllyOneMail / Autenticação

Autenticação

Integrações autenticam com uma API key por cliente, com escopos. O painel usa sessão de usuário (JWT), que a API também aceita.

API key

X-API-Key: zm_live_...

Crie a chave no painel do AllyOneMail (ou por POST /api/v1/auth/api-keys, com uma chave admin). O valor completo aparece só na criação; o AllyOneMail guarda apenas o hash (SHA-256). Se perder, gere outra e revogue a antiga. O prefixo zm_live_ é herança do nome anterior da plataforma.

Escopos

Escopo	Libera
`send`	Envio por `/api/v1/send`.
`read`	Leitura: domínios, eventos, supressões, webhooks, faturamento, warmup.
`domains`	Cadastrar e alterar domínios.
`suppress`	Só adicionar supressões (`POST /api/v1/suppressions`) — usado para sincronizar descadastros.
`privacy`	Direitos do titular: `/api/v1/privacy/export` e `/erasure`.
`admin`	Tudo, inclusive webhooks, usuários e chaves. Use só onde for necessário.

Chamada fora do escopo da chave responde 403 insufficient_scope.

Testar a chave

GET/api/v1/auth/me

curl https://smtp.allyone.com.br/api/v1/auth/me \
  -H "X-API-Key: zm_live_..."

{ "authType": "api_key", "clientId": "c1f0...", "agencyId": "a7d2...", "role": "api_key", "scopes": ["send", "read"] }

Para saber se a API está no ar sem autenticar: GET /api/status.

Rate limit

Por chave: o limite por minuto configurado na chave (padrão: 1.000). Ao exceder, 429 api_rate_limit_exceeded; o contador zera no minuto seguinte.
Por IP: 500.000 requisições por hora, com cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

Detalhes e formato dos erros em Erros e limites.

Referência completa

A especificação OpenAPI de todas as rotas de integração está publicada em smtp.allyone.com.br/docs (JSON em /docs/json) — importe no Postman ou Insomnia, ou gere um cliente.