Autenticação

Métodos de autenticação para diferentes contextos de uso.

Visão Geral

A plataforma expõe públicos diferentes — automações de integradores, o painel administrativo, sistemas de prestadores parceiros. Cada um tem necessidades distintas de segurança, e por isso há um método de autenticação para cada contexto (todos independentes entre si):

Por que métodos diferentes?

A escolha do método não é arbitrária — cada um resolve um problema de segurança específico:

• API Key + Secret — o mecanismo mais simples de máquina-a-máquina: dois headers fixos por aplicação. Ótimo para scripts diretos e integrações pontuais. É tudo ou nada dentro da aplicação (não tem granularidade de permissão) e a chave é longeva, então exige guardar bem o segredo. Mantido para compatibilidade das rotas clássicas.
• OAuth2 client_credentials Recomendado — pensado para automações. Você troca client_id/client_secret por um token de curta duração com escopos granulares (ex.: só mensagens:enviar, ou só agendamentos:read). Vantagens: o segredo longevo não trafega a cada chamada, o token expira sozinho (menor janela em caso de vazamento), e você concede a cada automação exatamente o mínimo necessário. É o único que dá acesso à superfície completa da API externa (pacientes, agendamentos, atendimentos).
• JWT Bearer Token — é para usuário humano operando o painel, não para automação. Por isso passa por proteções de conta (senha + MFA + reCAPTCHA + rate limit/lockout) e o token representa uma pessoa com um nível de acesso (ADMINISTRADOR, GESTOR, etc.), sujeito ao RBAC. Não use este método em integrações server-to-server.
• API Key do Prestador (nbwp_) — isola o parceiro do prestador num escopo próprio (só o endpoint de execução), com allowlist de IP e limite de requisições por credencial. Mantém o parceiro completamente separado da API do integrador da secretaria.

API Key + Secret (API — legado)

Utilize os headers X-Api-Key e X-Api-Secret em todas as requisições.

Obtendo as Credenciais

As credenciais são geradas automaticamente ao cadastrar uma aplicação no painel admin. O API Secret é exibido apenas uma vez — armazene-o em local seguro.

Exemplo de Requisição

Erros de Autenticação

Se as credenciais forem inválidas ou ausentes, a API retorna 401 Unauthorized:

JWT Bearer Token (API Admin)

A API Admin utiliza autenticação via JWT (JSON Web Token). Primeiro, obtenha um token através do endpoint de login.

Login

POST

Request body:

Resposta (200):

Proteções do login admin (MFA, reCAPTCHA e rate limit)

O login administrativo é protegido em camadas. A resposta do /api/admin/auth/login pode não trazer o token de imediato quando há um segundo fator:

• reCAPTCHA v3 (quando habilitado pelo admin) — o cliente web envia um token reCAPTCHA no corpo (recaptchaToken). Score baixo/ausente → 400.
• Rate limit por IP + lockout — excesso de requisições por IP, ou falhas demais por email/IP, retornam 429 com header Retry-After.
• MFA (TOTP) — obrigatório para ADMINISTRADOR e SUPORTE_SISTEMA. Quando o usuário tem MFA ativo, o login devolve {"mfaRequired": true, "ticket": "..."} (sem token). O segundo passo é POST /api/admin/auth/mfa/verificar com {ticket, codigo}, que então retorna o JWT. Perfis obrigatórios sem MFA recebem {"mfaSetupRequired": true, ...} (enrollment com QR Code) antes de concluir.

Esses fluxos valem para o painel web. Automações server-to-server devem usar a API Externa (API Key/Secret ou OAuth2), que não passa por MFA/reCAPTCHA.

Usando o Token

Inclua o token no header Authorization de todas as requisições à API Admin:

Erros de Login

Segurança

• API Keys são únicas por aplicação e podem ser regeneradas no painel admin
• Tokens JWT possuem prazo de expiração configurável
• Em produção, todas as requisições devem usar HTTPS
• O API Secret é armazenado como hash — não pode ser recuperado, apenas regenerado

Próximos Passos