Autenticação
Token global, JWT da instância e regras de autorização.
A API possui tres mecanismos independentes:
- Token global: administra criacao e listagem de instancias.
- JWT da instancia: autoriza conexao, mensagens individuais, chats, grupos, midia e webhooks por instancia.
- JWT de usuario: autoriza o fluxo de envio em lote e os eventos globais.
Token global
Configure AUTHENTICATION_GLOBAL_AUTH_TOKEN e envie um dos headers abaixo:
apikey: <token-global>Tambem sao aceitos x-api-key e apiKey. apikey e a forma recomendada. Se mais de um alias for enviado, todos precisam ter exatamente o mesmo valor.
Rotas protegidas pelo token global:
| Metodo | Rota | Situacao |
|---|---|---|
POST | /instance | Atual |
GET | /instance | Atual |
POST | /instance/create | Legada |
GET | /instance/fetchInstances | Legada |
Falhas: 401 quando o header nao existe ou o token e invalido; 400 quando aliases enviados ao mesmo tempo divergem.
Token da instancia
As rotas por instancia usam:
Authorization: Bearer <jwt-da-instancia>O JWT e assinado com HS256 e contem instanceName. O middleware compara esse claim com o nome presente na rota. Token ausente, malformado, expirado ou invalido retorna 401; claim referente a outra instancia retorna 403.
AUTHENTICATION_JWT_EXPIRES_IN=0 gera tokens de instancia sem exp e faz o validador de instancia ignorar expiracao. A validacao de nbf continua ativa.
Token de usuario
As rotas /message/batches... e /ws/global/events usam:
Authorization: Bearer <jwt-do-usuario>O JWT e assinado com HS256, precisa conter userId em formato UUID e precisa conter exp. A expiracao e sempre validada nesse fluxo, mesmo quando AUTHENTICATION_JWT_EXPIRES_IN=0.
Em Message Batch, userId e persistido como "ownerUserId" e limita criacao, consultas, itens, tentativas e acoes ao dono do lote.
Exemplo
curl "http://localhost:8084/instance/codechat/connection/status" \
-H "Authorization: Bearer $INSTANCE_TOKEN"Planos Basic e Pro
O runtime auditado nao diferencia planos. Nao existe claim de plano, middleware de entitlement, 402, URL de upgrade ou bloqueio por feature. Os endpoints Pro por instancia aceitam qualquer JWT de instancia valido, sujeitos as mesmas validacoes e ao estado da conexao. O recurso Pro /message/batches... usa o JWT de usuario descrito acima.
Consulte Endpoints Pro para a classificacao comercial e Erros para o envelope real.