Autenticação e segurança

A API possui duas credenciais com alcances diferentes. Ambas são credenciais bearer: quem obtiver o valor recebe as permissões correspondentes.

Escolha antes de integrar

Tudo que chega ao navegador pode ser lido pelo usuário, DevTools, extensões e scripts executados na página. Variáveis NEXT_PUBLIC_*, VITE_* e similares não protegem segredos.

token da instância

O header token autoriza operações de uma única instância: conexão, mensagens, chats, grupos, contatos, webhooks e demais recursos associados àquele número.

token: INSTANCE_TOKEN

O token pode ser usado diretamente em um dashboard no navegador quando o usuário autenticado é o dono daquela instância e já pode executar todas as operações dela. O backend do seu SaaS deve validar o tenant antes de entregar o token; não confie apenas no estado da interface.

Prefira manter o token em memória durante a sessão. Não o coloque no bundle, em código versionado, logs ou analytics. Persistir em localStorage aumenta o impacto de XSS e extensões maliciosas.

admintoken

O header admintoken administra o servidor e todas as instâncias. Ele permite operações como criar/listar instâncias, atualizar campos administrativos e rotacionar credenciais.

admintoken: ADMIN_TOKEN

Por padrão, mantenha o admintoken no backend. Um painel administrativo pode usá-lo diretamente no navegador somente quando todo usuário desse painel já é administrador do servidor inteiro e a exposição do token é uma decisão aceita explicitamente.

Nunca use esse modo em SaaS multi-tenant, painel entregue a clientes, dispositivo compartilhado ou aplicação com scripts de terceiros. Nesses casos, a interface chama o backend do SaaS, que valida usuário, tenant e permissão antes de usar a credencial.

SSE

O endpoint /sse aceita o token da instância na query string porque a API nativa EventSource não permite definir headers arbitrários:

/sse?token=INSTANCE_TOKEN&events=chats,messages

URLs podem aparecer em logs, histórico e ferramentas de observabilidade. Use HTTPS, evite registrar a query completa e prefira um proxy autenticado do seu backend quando o stream for aberto pelo navegador.

Armazenamento e rotação

• Armazene credenciais criptografadas ou em um secret manager.
• Não use NEXT_PUBLIC_*, VITE_* ou equivalentes para tokens.
• Redija token, admintoken e URLs SSE antes de registrar requests.
• Rotacione o token de instância por POST /instance/token/rotate quando houver exposição.
• Rotacione o token administrativo por POST /admin/token/rotate seguindo o intervalo aceito pela API.
• Depois da rotação, atualize consumidores e invalide caches imediatamente.

Matriz rápida

O OpenAPI é a fonte final para a segurança de cada rota; uma operação pode sobrescrever o requisito global.