---
title: Bearer Tokens
description: Admin-managed bearer tokens for server-to-server integrations — provisioning, usage, and rotation.
nav: Auth / Bearer
order: 1
version: v1
source: handwritten
updated: 2026-06-01
---

# 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](/v1/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:

```bash
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](/v1/auth/oauth) for per-user authentication.
- **Short-lived credentials** — if your security policy requires tokens to expire
  automatically, use [SMART backend services](/v1/auth/jwks) instead (5-minute TTL).
- **Multi-organization integrations** — each bearer token is scoped to one organization.
  You need one token per organization.