Segurança e Acesso

O Neppo Billing tem dois mecanismos de autenticação completamente separados, um
para cada tipo de consumidor.

Acesso interno (UI Angular) — rotas /api/**

• Login via Keycloak (SSO da empresa), sessão autenticada.

• Dois papéis:

  • billing.viewer — somente leitura

  • billing.operator — leitura + escrita (criar/editar Operations, Licenses,
    disparar jobs, etc.)

• Sem sessão válida, chamadas à API retornam 401 (navegação de página é
  redirecionada para o login).

• Endpoints que expõem segredos/credenciais (ex.: Chaves de API, configuração de
  integrações) exigem operator mesmo para leitura.

Acesso externo (integradores/sistemas) — rotas /api/v1/**

• Autenticação por chave de API, enviada no header Authorization: Bearer <chave>.

• Cada chave carrega escopos específicos, que limitam o que ela pode fazer:

  • operations:write — criar/editar Operations

  • dialog360:write — gerenciar vínculos do 360dialog (WhatsApp)

  • consumption:read — ler dados de consumo

• Chaves são geridas na seção "Chaves de API" das Configurações, na UI interna.

Por que dois mecanismos?

A API interna serve pessoas (via VPN, com login humano). A API externa
(/api/v1) serve máquina-a-máquina — sistemas parceiros consumindo dados de
consumo ou registrando operações, sem depender de sessão de navegador. São contratos
com ciclos de vida diferentes: a API externa é versionada (/api/v1, /api/v2…)
e muda com muito mais cuidado do que a UI interna, que pode evoluir livremente.

Ver também: Perguntas Frequentes · Glossário de Domínio