API administrativa

Referência das rotas principais da API Express. Os caminhos abaixo são relativos à aplicação; o proxy pode publicá-la sob /admin.

Não existe cadastro público. Exceto login e health, a API exige sessão válida. Operações autenticadas que alteram estado também exigem CSRF; as rotas de administração aplicam autorização ADMIN.

Acesso e sessão

Método	Rota	Finalidade
GET	/health	Liveness do processo; não certifica toda a cadeia
POST	/api/auth/login	Iniciar sessão; sujeito a rate limit
GET	/api/auth/me	Consultar identidade autenticada
GET	/api/auth/csrf	Recuperar CSRF para a sessão
POST	/api/auth/csrf/rotate	Rotacionar CSRF
POST	/api/auth/logout	Revogar sessão

Login é a exceção pública de autenticação; não necessita token CSRF prévio. O token da sessão vai em cookie HttpOnly, não no JSON para armazenamento pelo frontend.

Catálogo e auditoria

Método	Rota	Finalidade
GET	/api/devices	Consultar dispositivos
GET	/api/devices/:id	Consultar um dispositivo
PATCH	/api/devices/:id	Editar name, active e metadata
GET	/api/metric-definitions	Consultar métricas
PATCH	/api/metric-definitions/:key	Editar unit, description e active
GET	/api/audit-logs	Consultar histórico paginado
GET	/api/alert-statuses	Consultar estado agregado do alerta único A1

Não há criação/exclusão de dispositivos e métricas pela API. A identidade e a chave permanecem imutáveis.

Exemplo fictício de corpo, não uma chamada a executar:

{
  "name": "Inversor de exemplo",
  "active": true,
  "metadata": { "observacao": "Cadastro didático" }
}

Não usar metadata como cofre de senhas ou inventário de rede.

Administradores

Método	Rota	Finalidade
GET	/api/admin-users	Listar contas com projeção segura
POST	/api/admin-users	Criar outra conta ADMIN
PATCH	/api/admin-users/:id	Ativar/desativar outra conta
POST	/api/admin-users/:id/reset-password	Redefinir senha e revogar sessões

Não há exclusão, redefinição da própria senha ou desativação da própria conta por esses fluxos. O último ADMIN ativo é protegido, inclusive contra mutações concorrentes.

Respostas e limites

Sucesso usa envelope data; falha usa error com código e mensagem. HTTP 401 indica autenticação ausente/inválida; 403, acesso ou proteção rejeitada; outras respostas dependem da validação e do recurso. Não transformar qualquer falha em “servidor caiu”.

O estado dos alertas é um resumo de avaliação, não histórico nem comprovante de e-mail entregue. Veja segurança do Admin.

Revisão: 06/10/2026. Base: apps/admin/src/app.ts, validações e docs/admin.md. Para detalhes de limites de campo, consultar os schemas de validação no código.