API Tokens

API tokens provide a lightweight authentication mechanism for scenarios where a full OAuth flow would introduce unnecessary complexity or is not feasible. Their primary use case is anonymous or pseudonymous data collection — for example, clinical studies where patients scan a QR code to participate without revealing their identity to the study infrastructure.

The typical flow works like this: a study coordinator generates a one-time token for each participant, encodes it in a QR code, and hands it to the participant. The participant's app scans the QR code, redeems the one-time token for a durable token, and uses that for all subsequent requests. The participant never needs to create an account or go through an identity provider.

When to use API tokens vs. OAuth / Azure Identity

While API tokens can be used for device authentication or service-to-service communication, it is strongly recommended to use OAuth 2.0 or Azure Identity for those scenarios. OAuth and Azure Identity provide stronger security guarantees (token rotation, scoped permissions, audit trails through the identity provider) and integrate better with enterprise infrastructure. Reserve API tokens for situations where simplicity and anonymity are the primary requirements.

Token Types

Fire Arrow supports two types of API tokens:

Type	Prefix	Usage
Durable	fa_	Long-lived tokens for ongoing programmatic access
One-time	fo_	Single-use tokens that are exchanged for a durable token (e.g., QR code patient onboarding)

Both token types are always linked to a specific FHIR resource (Patient, Practitioner, RelatedPerson, or Device). The linked resource determines the client's role for authorization, just like with JWT-based authentication.

Generating Tokens

Tokens are generated by calling FHIR operations on the target resource.

Generate a Durable Token

POST /fhir/Patient/123/$generate-durable-token HTTP/1.1
Authorization: Bearer <jwt-or-api-token>
Content-Type: application/fhir+json

Generate a One-Time Token

POST /fhir/Patient/123/$generate-one-time-token HTTP/1.1
Authorization: Bearer <jwt-or-api-token>
Content-Type: application/fhir+json

Both operations return a response containing the token:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "access_token",
      "valueString": "fa_abc123def456..."
    },
    {
      "name": "expires_in",
      "valueInteger": 31536000
    },
    {
      "name": "fhir_identity_reference",
      "valueString": "Patient/123"
    }
  ]
}

warning

The access_token value is shown only once in the generation response. It cannot be retrieved later. Store it securely.

These operations work on any identity resource type:

• POST /fhir/Patient/{id}/$generate-durable-token
• POST /fhir/Practitioner/{id}/$generate-durable-token
• POST /fhir/RelatedPerson/{id}/$generate-durable-token
• POST /fhir/Device/{id}/$generate-durable-token

The same applies for $generate-one-time-token.

Using API Tokens

Include the token in the Authorization header like any other bearer token:

GET /fhir/Patient/123 HTTP/1.1
Authorization: Bearer fa_abc123def456...

Fire Arrow detects the fa_ or fo_ prefix and validates the token against its internal store rather than delegating to an OAuth provider.

Redeeming One-Time Tokens

One-time tokens cannot be used for regular API access. Instead, they are exchanged for a durable token using the $redeem-token operation:

POST /fhir/$redeem-token HTTP/1.1
Authorization: Bearer fo_xyz789...
Content-Type: application/fhir+json

Response:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "access_token",
      "valueString": "fa_newtoken123..."
    },
    {
      "name": "expires_in",
      "valueInteger": 31536000
    },
    {
      "name": "fhir_identity_reference",
      "valueString": "Patient/123"
    }
  ]
}

After redemption, the one-time token is invalidated and cannot be used again. This flow is ideal for QR-code-based patient onboarding: generate a one-time token, encode it in a QR code, and let the patient's app redeem it for a durable token on first scan.

Authorization Requirements

Generating API tokens requires two layers of authorization:

1. Operation rule -- The caller must have an authorization rule granting the generate-durable-token or generate-one-time-token operation.
2. Update permission -- The caller must also have update permission on the target resource, since generating a token is a modification of that resource's access.

For example, to allow practitioners to generate tokens for patients:

fire-arrow:
  authorization:
    rules:
      - client-role: Practitioner
        resource: Patient
        operation: generate-durable-token
        validator: PractitionerCompartment

      - client-role: Practitioner
        resource: Patient
        operation: update
        validator: PractitionerCompartment

Configuration

API token settings are configured under fire-arrow.authentication.api-tokens:

fire-arrow:
  authentication:
    api-tokens:
      hmac-secret: ${API_TOKEN_SECRET}
      durable-token-expiration: 365d
      one-time-token-expiration: 7d

Property	Description
hmac-secret	The secret key used to sign and verify API tokens.
durable-token-expiration	How long durable tokens remain valid. Defaults to 365d.
one-time-token-expiration	How long one-time tokens remain valid before they must be redeemed. Defaults to 7d.

HMAC Secret in Production

The hmac-secret is required for production deployments. If not configured, Fire Arrow generates a random secret at startup -- meaning all previously issued tokens become invalid after a restart.

Use a stable, securely stored secret (e.g., from Azure Key Vault or an environment variable):

fire-arrow:
  authentication:
    api-tokens:
      hmac-secret: ${API_TOKEN_SECRET}

Admin API

Active API tokens can be managed through the Admin API at /admin-api/api-tokens. This endpoint supports listing and revoking tokens.

GET /admin-api/api-tokens HTTP/1.1
Authorization: Bearer <jwt-with-admin-scope>

note

The Admin API requires a JWT with the configured admin scope or admin role. It is not accessible using API tokens -- only JWT-authenticated users with admin privileges can manage tokens.