Autenticacao

A NeoGo API usa autenticacao baseada em API keys via header HTTP. Existem dois niveis de acesso: administrador e instancia.

Visao Geral

Todas as requisicoes a API devem incluir o header apikey:

curl -H "apikey: SUA_CHAVE_AQUI" http://localhost:4000/endpoint

Nivel	Header	Acesso	Rotas
Admin (Global)	`apikey: GLOBAL_API_KEY`	Gerenciamento de instancias	`/instance/create`, `/instance/all`, `/instance/delete`, `/admin/*`
Instancia	`apikey: TOKEN_DA_INSTANCIA`	Operacoes da instancia	`/send/`, `/message/`, `/chat/`, `/group/`, `/user/*`, etc.

Chave Admin (Global API Key)

A chave global e definida via variavel de ambiente GLOBAL_API_KEY no servidor. Ela concede acesso a rotas administrativas:

Criar e deletar instancias
Listar todas as instancias
Configurar proxy por instancia
Forcar reconexao
Rotacionar tokens
Gerenciar failover
Gerenciar alertas

# Exemplo: listar todas as instancias
curl http://localhost:4000/instance/all \
  -H "apikey: SUA_CHAVE_GLOBAL"

Seguranca: A chave global concede acesso total ao servidor. Nunca exponha em codigo frontend, repositorios publicos ou logs. Use variaveis de ambiente.

Token de Instancia

Ao criar uma instancia, a API retorna um token unico. Esse token e usado para todas as operacoes especificas daquela instancia:

# Criar instancia e guardar o token
curl -X POST http://localhost:4000/instance/create \
  -H "apikey: SUA_CHAVE_GLOBAL" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "producao"}'

# Resposta:
# {
#   "instanceId": "abc-123",
#   "token": "9f4e2d1a8b7c6e5f4d3a2b1c...",
#   ...
# }

# Usar o token para enviar mensagem
curl -X POST http://localhost:4000/send/text \
  -H "apikey: 9f4e2d1a8b7c6e5f4d3a2b1c..." \
  -H "Content-Type: application/json" \
  -d '{"number": "5511999999999", "text": "Ola!"}'

Rotacao de Token

Por seguranca, voce pode rotacionar o token de uma instancia a qualquer momento. O token antigo continua funcionando por um periodo de graca configuravel.

# Rotacionar token (requer chave admin)
curl -X POST http://localhost:4000/instance/rotate-token/INSTANCE_ID \
  -H "apikey: SUA_CHAVE_GLOBAL"

# Resposta:
# {
#   "newToken": "novo-token-gerado...",
#   "oldTokenValidUntil": "2026-05-06T10:00:00Z"
# }

Como funciona a rotacao

Um novo token e gerado e passa a ser o token primario
O token antigo e armazenado em hash SHA-256 na tabela TokenHistory
Durante o periodo de graca, ambos os tokens sao aceitos
Apos o periodo de graca, o token antigo e invalidado

Dica: Rotacione tokens periodicamente em ambiente de producao. Use o periodo de graca para atualizar suas integracoes sem downtime.

Protecoes de Seguranca

O middleware de autenticacao inclui diversas protecoes:

Protecao	Descricao
Validacao de formato	Tokens muito curtos ou com formato invalido sao rejeitados antes de consultar o banco (prevencao contra DoS)
Rate limiting	Limites por IP e por API key, com sliding window. Suporta Redis para limites distribuidos
Request ID	Cada requisicao recebe um UUID unico via header `X-Request-ID` para rastreamento
JID Validation	Numeros de telefone sao normalizados automaticamente para formato WhatsApp JID
CORS	Configuravel via `CORS_ORIGIN` (padrao: `*`)

Autenticacao JWT (Manager UI)

Alem da autenticacao por API key, o Manager UI utiliza autenticacao JWT para sessoes de usuario. Isso e usado internamente pela interface web e nao e necessario para integracoes via API REST.

Endpoint	Descricao
`POST /auth/register`	Registrar novo usuario
`POST /auth/login`	Login (retorna JWT)
`POST /auth/refresh`	Renovar token JWT
`GET /auth/me`	Dados do usuario autenticado
`PATCH /auth/me`	Atualizar perfil
`POST /auth/me/password`	Alterar senha

Erros de Autenticacao

Respostas comuns quando a autenticacao falha:

# 401 Unauthorized - Token invalido ou ausente
{
  "error": "invalid api key"
}

# 401 Unauthorized - Token expirado (apos rotacao)
{
  "error": "token expired, please use the new token"
}

# 429 Too Many Requests - Rate limit excedido
{
  "error": "rate limit exceeded",
  "retryAfter": 60
}

Boas Praticas

Use variaveis de ambiente para armazenar chaves, nunca hardcode
Rotacione tokens periodicamente em producao
Use HTTPS em producao (reverse proxy com nginx ou Caddy)
Configure CORS_ORIGIN com o dominio especifico do seu frontend
Monitore rate limits — aumente se necessario via configuracao
Use tokens diferentes por ambiente (dev/staging/prod)