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 continua 401).

API Key#

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

text 
X-API-Key: ctc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Formato: ctc_ + 64 caracteres hex (32 bytes aleatorios)
  • Chaves emitidas antes da renomeacao para Catcher (2026-05) usam o prefixo legado bza_ e continuam válidas — a API aceita os dois prefixos, não e preciso rotacionar
  • 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: <ctc_token> X-API-Key: ctc_4615fb31...

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

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

Sessão do navegador (cookies)#

O Console usa um terceiro modo, exclusivo para navegador:

  • O access token JWT fica apenas em memória (nunca em localStorage).
  • O refresh usa o cookie biazap_refresh_token (HttpOnly, rotacionado a cada uso).
  • Requests unsafe (POST/PATCH/DELETE) do navegador devem enviar o header X-CSRF-Token, lido do cookie biazap_csrf_token. Ausente ou divergente → 403 CSRF_INVALID.
  • Integrações server-to-server (API key ou Bearer JWT puro) NÃO precisam de CSRF — o requisito de CSRF so vale para sessões de navegador com cookie.

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)