API de painel

Toda rota que o painel fala, num lugar só: método, caminho, papel exigido e o que cada uma devolve. As rotas vivem em backend/src/routes/ e não usam prefixo — cada arquivo escreve o caminho completo por extenso. Autenticação, papéis e as exceções ao piso vêm primeiro; as famílias de rota vêm na sequência.

Autenticação e papéis#

A superfície de painel tem uma única credencial: o cookie de sessão assinado — nome session_id, httpOnly, validade de 7 dias, no formato id da sessão seguido de um HMAC. Um cookie cru sem assinatura só foi aceito até LEGACY_UNSIGNED_UNTIL, 2026-10-01. A antiga credencial por bearer ADMIN_API_KEY foi removida: não existe no schema de ambiente e a sessão sentinela que ela criava é rejeitada mesmo se sobreviver no Redis. Em desenvolvimento, AUTH_DISABLED=true abre todas as rotas /api/* com aviso no boot — e a produção recusa o boot com essa variável ligada.

Toda mutação — POST, PUT, PATCH e DELETE — exige também o header X-CSRF-Token. O token é um HMAC derivado do segredo do cookie e do id da sessão (synchronizer sem estado), e o próprio GET /api/auth/me o devolve para o front. A verificação roda antes da lista de paths públicos e falha com 403 csrf_invalid em comparação em tempo constante. A única isenção é POST /api/auth/logout: um logout forjado só desloga, e exigir o token prenderia o usuário com sessão já expirada.

O piso automático por método

O papel mínimo de cada rota é automático, por método HTTP — nenhuma rota nova nasce aberta por esquecimento:

A hierarquia de papéis

Três papéis — OWNER > ADMIN > MEMBER — comparados por rank: quem tem rank igual ou superior ao exigido passa, e papel ausente falha fechado. O requireRole por rota roda depois do guard global: sem tenant responde 401; papel insuficiente responde 403 nomeando o mínimo exigido. Na prática o único valor usado é ADMIN — nenhuma rota exige OWNER diretamente; o papel só vale pela herança da hierarquia.

O que é público

Doze prefixos escapam do guard inteiro, por match de startsWith:

Chaves de provedor#

O CRUD e as ações em lote das contas de provedor. A criação passa pelo loadBalancer.addKey, e GET /api/keys/usage devolve as janelas de 5h e semanal de cada conta de plano da organização.

• GET /api/keys/usage
• GET /api/keys/options
• POST /api/keys
• PUT /api/keys/:id
• DELETE /api/keys/:id
• PUT /api/keys/:id/toggle
• PATCH /api/keys/bulk-model
• POST /api/keys/:id/duplicate
• PUT /api/keys/:id/reset
• POST /api/keys/bulk-reactivate
• POST /api/keys/bulk-disable
• POST /api/keys/:id/clear-error

Grupos#

Três famílias de grupos com o mesmo desenho de CRUD. Grupos de chaves agregam contas de provedor com strategy e hedgeConfig; grupos de config agregam URLs; e os grupos compartilhados são os que a org da Nomad libera para outras organizações escolherem (PLAT-12).

• GET /api/groups
• GET /api/groups/:id
• POST /api/groups
• PUT /api/groups/:id
• DELETE /api/groups/:id
• GET /api/config-groups
• GET /api/config-groups/:id
• POST /api/config-groups
• PUT /api/config-groups/:id
• DELETE /api/config-groups/:id
• GET /api/shared-key-groups

Grupos de chaves de provedor — groups.ts

Grupos de config (URLs) — configGroups.ts

Grupos compartilhados — sharedGroups.ts

Configs de URL#

As URLs do proxy. Criação e atualização aceitam as atribuições de usuário na mesma chamada; PUT /api/configs/:id/assignments define só os userIds atribuídos. A visibilidade RESTRICTED é o que esconde o detalhe do MEMBER.

• GET /api/configs
• GET /api/configs/:id
• POST /api/configs
• PUT /api/configs/:id
• PUT /api/configs/:id/assignments
• POST /api/configs/:id/toggle
• POST /api/configs/:id/duplicate
• DELETE /api/configs/:id
• GET /api/configs/stats/summary

Requests#

O log de requests proxied: listagem com filtros e sort, resumo, facets, exportação e agregados por URL, grupo e chave. Tudo é leitura, exceto o DELETE por ids.

• GET /api/requests
• GET /api/requests/summary
• GET /api/requests/facets
• GET /api/requests/export
• GET /api/requests/stats/by-config
• GET /api/requests/stats/by-group
• GET /api/requests/stats
• GET /api/requests/:id
• GET /api/requests/api-key-stats
• DELETE /api/requests

Métricas e health#

Agregados para as telas de insights e os sinais de operação. /api/health e /api/pool-stats são públicos — é o orquestrador que os consulta; o resto exige sessão, e duas leituras sobem para ADMIN.

• GET /api/metrics/advanced
• GET /api/metrics/latency
• GET /api/metrics/costs
• GET /api/metrics/activity
• GET /api/metrics/health
• GET /api/metrics/models
• GET /api/metrics/insights
• GET /api/metrics/counters
• GET /api/health
• GET /api/health/db
• GET /api/pool-stats
• GET /api/stats
• POST /api/cleanup/run
• GET /api/cleanup/stats

Modelos e provedores#

Consultas ao vivo sobre o que cada chave suporta: modelos disponíveis, specs, capacidades por provedor e o estado de rate limit. A lista de providers vem do registry, e /api/test-connection valida credencial com authType/cookies antes de cadastrar.

• POST /api/models/fetch
• GET /api/providers
• GET /api/providers/capabilities
• POST /api/models/specs
• GET /api/models/specs/cached
• GET /api/ratelimit/status
• POST /api/test-connection

OAuth#

Quatro arquivos, quatro fluxos — Claude, GitHub/Copilot, Codex e Meta — todos gravando a organização dona na sessão do fluxo e consultando o andamento por sessionId. O device flow do Copilot, do Codex e do Meta tem os mesmos dois passos: init e poll.

• POST /api/oauth/init
• POST /api/oauth/callback
• GET /api/oauth/callback
• GET /api/oauth/status/:sessionId
• POST /api/oauth/github/init
• POST /api/oauth/github/callback
• GET /api/oauth/github/callback
• GET /api/oauth/github/status/:sessionId
• POST /api/copilot/device/init
• POST /api/copilot/device/poll
• POST /api/github/add-token
• POST /api/codex/device/init
• POST /api/codex/device/poll
• POST /api/meta/device/init
• POST /api/meta/device/poll

Claude — oauth.ts

GitHub e Copilot — githubOAuth.ts

Codex e Meta — device flow

Conta e autenticação#

O login é só pela Conta Nommand (OIDC): o app não tem login próprio, cadastro nem gestão de empresa. As rotas /auth/* são redirects do fluxo; as de /api/auth/* servem o front e os webhooks da Conta.

• GET /api/auth/mode
• GET /auth/sso
• GET /auth/callback
• GET /api/auth/oidc/topbar
• POST /api/auth/oidc/backchannel-logout
• POST /api/auth/oidc/provisioning
• GET /api/auth/me
• POST /api/auth/logout

Chaves de acesso ao proxy#

As chaves sk-lb- que os clientes usam no proxy. Pessoais: o usuário cria e revoga as próprias. De serviço e as de terceiros na organização: só ADMIN.

• GET /api/account/keys
• POST /api/account/keys
• DELETE /api/account/keys/:id
• GET /api/organizations/:id/api-keys
• DELETE /api/organizations/:id/api-keys/:keyId
• GET /api/organizations/:id/service-keys
• POST /api/organizations/:id/service-keys
• PUT /api/organizations/:id/service-keys/:keyId
• DELETE /api/organizations/:id/service-keys/:keyId

Organizações e auditoria#

A organização é o tenant de tudo. A leitura é de membro; atualizar a org, ver membros e ler o log de auditoria são de ADMIN.

• GET /api/organizations
• GET /api/organizations/:id
• PUT /api/organizations/:id
• GET /api/organizations/:id/members
• GET /api/organizations/:id/audit

Plataforma#

A visão cross-org para o administrador da plataforma. A guarda é própria — um preHandler que checa User.isPlatformAdmin antes de qualquer handler — e quase todos os handlers rodam dentro de runAsPlatform, o escape do tenancy.

• GET /api/platform/overview
• GET /api/platform/organizations
• GET /api/platform/organizations/:id
• GET /api/platform/health
• GET /api/platform/nomad
• POST /api/platform/nomad
• GET /api/platform/shared-groups
• PUT /api/platform/shared-groups/:groupId
• GET /api/platform/keys/usage
• POST /api/platform/keys/:id/usage-limit/reset
• GET /api/platform/requests

WebSocket#

O stream realtime do log de requests. Não é REST: é upgrade de WebSocket, em dois caminhos que apontam para o mesmo handler — sem e com o prefixo /api, porque o reverse-proxy pode fazer strip dele.

• GET /ws/requests
• GET /api/ws/requests

O protocolo é um ping-pong de três tipos:

servidor → cliente   {"type": "hello" | "request" | "ping"}
cliente → servidor   {"type": "ping"}

Rotas fora do piso#

O piso por método tem duas listas de exceção em middleware/auth.ts. O que escapa delas é MEMBER-read comum: /api/providers e /api/providers/capabilities, as métricas fora de health e counters, os requests fora de api-key-stats e stats/by-group, /api/organizations e /api/account/keys.