Auth
The Huli Public API supports three authentication modes. All three are available in v1. Pick based on your integration type.
Decision guide
| Mode | When to use |
|---|---|
| Admin bearer token | Server-to-server integrations where a human admin provisions the key once. Simplest path to a working integration. No JWT signing required. |
| SMART backend services | Automated M2M integrations that need short-lived tokens, key rotation without human involvement, or auditable client identity. Requires RS384 key pair and a reachable JWKS endpoint. |
| Interactive OAuth (PKCE) | User-facing applications where each end user authenticates individually — patient portals, clinician apps, data access requests tied to a specific practitioner identity. |
If you are not sure, start with the admin bearer token. It works for the majority of back-office integrations and can be replaced later without changing the request format — both modes set Authorization: Bearer <token>.
Token endpoint
All three modes issue tokens via:
/auth/tokenBase URL: https://api.huli.ai (not under /fhir).
Scopes
Scopes are requested at token issuance and enforced on every resource operation. The scope format is system/<Resource>.<perms> where perms are combinations of r (read), s (search), c (create), u (update).
See the Scope reference for the complete table. Cross-links from the individual auth mode pages point to specific scope entries.
Token lifetime
| Mode | Token TTL |
|---|---|
| Admin bearer | Does not expire (revoke from Practice Settings) |
| SMART backend services | 5 minutes — must be refreshed using client_credentials again |
| Interactive OAuth | Configurable per app registration (default: 1h access token, 30d refresh token) |
SMART discovery
The discovery document for SMART configuration is at:
GET /fhir/.well-known/smart-configuration
Full URL: https://api.huli.ai/fhir/.well-known/smart-configuration
It returns the token endpoint, JWKS URI, scopes supported, and grant types. Any SMART-compliant client library can use this to configure itself automatically.
What's in each section
- Bearer tokens — provisioning, rotation, and usage. Copy-paste path.
- JWKS / SMART backend services — key pair generation, JWKS endpoint setup, client assertion format, token exchange, replay protection.
- Interactive OAuth — app registration, authorization code flow, PKCE, redirect URIs, and consent screen behavior.