Autenticacao

API Key para hospitais e clinicas

As rotas operacionais usam o header:

X-API-Key: sm_live_...

Scopes (permissoes)

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

Scopes principais

• interactions:check: necessario para /api/v1/interactions/check, /api/v1/interactions/recheck, /api/v1/pharmacy/check, MCP de interacoes e fluxos relacionados de chat/audio que dependem da analise.
• analyses:read: leitura de analises no REST e MCP.
• usage:read: leitura de consumo.
• billing:read: leitura financeira.

Whitelist de IP (obrigatorio quando configurada)

Quando o admin define whitelist na API key (allowed_ips), somente requisicoes vindas desses IPs/CIDRs serao aceitas.

Exemplos de regras:

• 177.10.20.30
• 10.10.0.0/16

Se o IP nao estiver liberado, a API responde:

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

JWT para administracao

As rotas administrativas usam token Bearer obtido em:

• POST /api/v1/auth/login

Header:

Authorization: Bearer <token>

Seguranca recomendada

• Nao salvar chaves em codigo-fonte.
• Rotacionar chaves periodicamente.
• Restringir por IP quando aplicavel.