Autenticação

Toda rota administrativa aceita Authorization: Bearer <token>, onde o token é um destes dois:

ADMIN_TOKEN (break-glass)

Um token fixo, definido na configuração do backend. Sempre tem papel admin, nunca expira. Pensado como acesso de emergência/operação — não é o caminho normal para um operador do dia a dia.

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://sua-instancia.exemplo/instance/all

Sessão de usuário

Login usuário+senha, devolvendo um token opaco (wgs_...) que expira em 12 horas e é revogável a qualquer momento (logout, troca de senha, desativação do usuário).

curl -X POST -H "Content-Type: application/json" \
  -d '{"login":"operador","password":"..."}' \
  https://sua-instancia.exemplo/auth/login
# → {"token":"wgs_...","user":{...}}

Rota	Quem pode	Descrição
POST /auth/login {login,password} → {token,user}	pública	A mensagem de erro é idêntica para login inexistente, senha errada, conta trancada ou desativada — não dá para descobrir por tentativa qual é o caso (anti-enumeração)
POST /auth/logout	autenticado	Revoga só a sessão atual
GET /auth/me	autenticado	{"kind":"break-glass"} (via ADMIN_TOKEN) ou {"kind":"session","user":{...}}
POST /auth/password {currentPassword,newPassword}	sessão	Troca a própria senha — revoga todas as sessões, inclusive a atual (é preciso logar de novo)

Confirmado ao vivo: GET /auth/me com ADMIN_TOKEN devolve exatamente {"kind":"break-glass"}; um login com credenciais inexistentes devolve o mesmo 401 {"code":"unauthorized","message":"credenciais ausentes ou inválidas"} que qualquer outra rota sem autenticação — mesma mensagem genérica, sem distinguir o motivo.

Papéis

• admin — gerencia usuários, vê e edita qualquer instância, sem cota.
• user — só as próprias instâncias, sujeito a uma cota fixa (maxInstances).

Gestão de usuário é admin-only (POST /users, GET /users, PATCH /users/{id}, .../disable, .../enable, .../reset-password) — fora do escopo desta documentação de integração; ver o painel administrativo.

Token de instância (self-service)

Para automatizar o envio/consulta de uma instância específica, use o token dela (devolvido só na criação ou na rotação) no header token — nunca Authorization, e nunca com :id na URL: a instância se identifica por si mesma.

curl -H "token: <TOKEN_DA_INSTANCIA>" \
  https://sua-instancia.exemplo/instance/status

Isso existe para evitar IDOR: com o token de instância você nunca escolhe qual instância consultar — só pode ser a sua.