for Developers

Bearer Tokens

Admin-managed bearer tokens are the fastest path to a working integration. A human admin creates the key once in Practice Settings; the token is used directly in the Authorization header with no signing, no token exchange, and no expiry.

Provisioning

  1. Log in to HuliPractice as an admin.
  2. Navigate to Settings → Integrations → API Keys.
  3. Click New API key.
  4. Select the scopes your integration needs (see Scopes).
  5. Copy the token. It is shown once.

The token is a random 256-bit value encoded as a hex string. It does not encode any claims — the server resolves the associated organization and scopes by looking up the hash.

Usage

Set the token in the Authorization header on every request:

curl https://api.huli.ai/fhir/R4/Patient?_count=1 \
  -H "Authorization: Bearer $HULI_API_KEY" \
  -H "Accept: application/fhir+json"

No additional headers are required. The server resolves the organization from the token.

Storing the token

  • Store in a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, etc.) or an environment variable.
  • Do not commit to source control.
  • Do not include in client-side bundles — bearer tokens are server-side credentials only.
  • Do not log the Authorization header. Redact it in request traces.

Rotation

Tokens do not expire on a schedule. Rotate them:

  • After any suspected compromise.
  • As part of a regular security rotation policy (recommended: every 90 days).
  • When the admin who provisioned the key leaves the organization.

Rotation is atomic: in Practice Settings, click Rotate on the key. The new token is issued and the old one is revoked immediately. There is no grace period for simultaneous use of old and new tokens — update your deployment before rotating.

For zero-downtime rotation:

  1. Create a new API key with the same scopes (do not rotate the existing one yet).
  2. Deploy the new key to your infrastructure.
  3. Verify requests are succeeding with the new key.
  4. Return to Practice Settings and revoke the old key.

Revocation

Revoked tokens return 401 with HPB-00106. Revoke from Practice Settings or by contacting your organization admin. Revoked tokens cannot be re-enabled — create a new key.

Scope binding

The scopes associated with a bearer token are fixed at provisioning time. A request operation that requires a scope not on the token returns 403 with HPB-00104.

To add scopes, create a new key with the required scopes. You cannot add scopes to an existing key after provisioning.

Limitations

Bearer tokens are not suitable for:

  • User-facing applications — the token represents the organization, not an individual user. Use interactive OAuth for per-user authentication.
  • Short-lived credentials — if your security policy requires tokens to expire automatically, use SMART backend services instead (5-minute TTL).
  • Multi-organization integrations — each bearer token is scoped to one organization. You need one token per organization.