Pular para o conteúdo principal
Docs vAtual•API —
Versão: Atual

Autenticação

API Key para hospitais e clínicas​

As rotas operacionais usam o header:

X-API-Key: sm_live_...

Scopes (permissões)​

  • Cada API key tem scopes (ex.: interactions:check, hospital:read, billing:read).
  • Se scopes estiver vazio ([]), a key não acessa endpoints protegidos (retorna 403).
  • Wildcards são suportados somente quando configurados explicitamente:
    • *: acesso a qualquer scope
    • namespace:*: acesso a todos os scopes do namespace, por exemplo interactions:*

Scopes principais​

  • interactions:check: necessário para /api/v1/interactions/check, /api/v1/interactions/recheck, /api/v1/pharmacy/check, MCP de interações e fluxos relacionados de chat/áudio que dependem da análise.
  • analyses:read: leitura de análises no REST e MCP.
  • usage:read: leitura de consumo.
  • billing:read: leitura financeira.

Whitelist de IP (obrigatória quando configurada)​

Quando o administrador da organização define whitelist na API key (allowed_ips), somente requisições vindas desses IPs/CIDRs serão aceitas.

Para descobrir o IP que a SauBit enxerga na sua saída (NAT/proxy do hospital), chame GET /api/v1/health a partir do mesmo servidor: o campo client_ip da resposta é o endereço que deve constar na whitelist.

Exemplos de regras:

  • 177.10.20.30
  • 10.10.0.0/16

Se o IP não estiver liberado, a API responde:

  • HTTP 403
  • detail: IP não permitido para esta API key

Segurança recomendada​

  • Não salvar chaves em código-fonte.
  • Rotacionar chaves periodicamente.
  • Restringir por IP quando aplicável.
Autenticação administrativa

As rotas administrativas (gestão de organizações, chaves, faturamento, governança) usam autenticação própria (JWT) e são documentadas separadamente no Swagger Admin, com acesso restrito à equipe operacional da SauBit.