Autenticação

1. Autenticação#

A API suporta dois métodos de autenticação:

JWT (Bearer Token)#

Obtido via /v1/auth/login. Enviar no header:

text 
Authorization: Bearer <jwt_token>
  • Algoritmo: HS256
  • Expiracao padrão: 15 minutos
  • Claims: company_id, user_id, role, is_superadmin
  • Revalidacao de empresa: em cada request autenticada com JWT (exceto is_superadmin), o servidor consulta o master DB para garantir que a empresa existe e está active. Empresa inexistente → 403 com company not found; suspensa → 403 com company suspended; falha de banco nessa consulta → 503 com service unavailable. O mesmo critério de empresa ativa se aplica a API key (token inválido contínua 401).

API Key#

Obtida via /v1/tokens ou retornada no registro (POST /v1/auth/register). Enviar no header:

text 
X-API-Key: bza_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Formato: bza_ + 60 caracteres hex
  • Armazenada como hash SHA256 no banco (nunca em texto plano)
  • Pode ser revogada a qualquer momento

⚠️ ATENÇÃO — NÃO CONFUNDIR OS HEADERS:

Tipo de credencial Header correto Exemplo
JWT (sessão browser) Authorization: Bearer <jwt> Authorization: Bearer eyJhbG...
API Key (integração/SDK) X-API-Key: <bza_token> X-API-Key: bza_4615fb31...

Usar Authorization: Bearer bza_... retorna 401 TOKEN_INVALID — o middleware JWT tenta decodificar o bza_ como JWT e falha. O token bza_ DEVE ser enviado via X-API-Key.

O token retornado no POST /v1/auth/register é um API key (bza_...), NÃO um JWT. Use X-API-Key para todas as chamadas subsequentes com esse token.

Roles (Papeis)#

Role Descricao
owner Dono da empresa. Acesso total: usuários, tokens, instâncias, mensagens
admin Administrador. Gerencia instâncias, webhooks, filas
agent Agente. Envia mensagens, acessa chats/contatos
superadmin Administrador da plataforma. Acesso a rotas /v1/admin/*

Acesso por Role#

Recurso owner admin agent
Tokens e Usuários x - -
Instâncias (CRUD) x x -
Mensagens x x x
Chats e Contatos x x x
Presença e Perfil x x x
Grupos x x x
Mídia x x x
Fila x x -
Webhooks x x -
Admin superadmin only - -

Rate Limiting#

  • Baseado em Redis, por empresa
  • Limite configuravel por plano (padrão: 60 req/min)
  • Rotas /v1/admin/* não aplicam throttling adicional por request; o acesso depende de JWT válido com is_superadmin=true
  • Headers de resposta:
    • X-RateLimit-Limit - Total permitido por minuto
    • X-RateLimit-Remaining - Restantes no periodo
    • X-RateLimit-Reset - Timestamp Unix do reset
    • Retry-After - Segundos para aguardar (quando 429)