---
title: Auth
description: Three authentication modes for the Huli Public API — admin-managed bearer tokens, SMART backend services (M2M), and interactive OAuth with PKCE. Pick the right one for your integration.
nav: Auth
order: 0
version: v1
source: handwritten
updated: 2026-06-01
---

# 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](/v1/auth/bearer)      | 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](/v1/auth/jwks)    | 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)](/v1/auth/oauth) | 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:

<Endpoint method="POST" path="/auth/token" />

Base 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](/v1/scopes) 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](/v1/auth/bearer)** — provisioning, rotation, and usage. Copy-paste
  path.
- **[JWKS / SMART backend services](/v1/auth/jwks)** — key pair generation, JWKS
  endpoint setup, client assertion format, token exchange, replay protection.
- **[Interactive OAuth](/v1/auth/oauth)** — app registration, authorization code flow,
  PKCE, redirect URIs, and consent screen behavior.