Skip to main content
Docs vCurrent•API —
Version: Current

Authentication

API Key for hospitals and clinics​

Operational routes use the header:

X-API-Key: sm_live_...

Scopes (permissions)​

  • Each API key has scopes (e.g. interactions:check, hospital:read, billing:read).
  • If scopes is empty ([]), the key cannot access protected endpoints (returns 403).
  • Wildcards are supported only when explicitly configured:
    • *: access to any scope
    • namespace:*: access to all scopes in the namespace, e.g. interactions:*

Main scopes​

  • interactions:check: required for /api/v1/interactions/check, /api/v1/interactions/recheck, /api/v1/pharmacy/check, the interactions MCP, and related chat/audio flows that depend on the analysis.
  • analyses:read: read analyses over REST and MCP.
  • usage:read: read usage.
  • billing:read: read billing data.

IP allowlist (required when configured)​

When the admin sets an allowlist on the API key (allowed_ips), only requests coming from those IPs/CIDRs are accepted.

Example rules:

  • 177.10.20.30
  • 10.10.0.0/16

If the IP is not allowed, the API responds:

  • HTTP 403
  • detail: IP não permitido para esta API key
  • Do not store keys in source code.
  • Rotate keys periodically.
  • Restrict by IP where applicable.
Administrative authentication

Administrative routes (organization management, keys, billing, governance) use their own authentication (JWT) and are documented separately in the Admin Swagger, with access restricted to the SauBit operations team.