Access Tokens

Access tokens are short-lived credentials that authorize requests to Health Gorilla APIs. You must include the token in the Authorization header of each request.

• Issued after a successful authorization flow (e.g., client credentials or authorization code)
• Required for all authenticated API requests (Authorization: Bearer {token})
• Encodes key metadata, including:
  • Scopes granted (e.g., patient/*.read)
  • Associated user or client identity (sub)
  • FHIR version and base URL
  • Expiration time (exp)

Tokens must be stored securely and never shared across users or sessions.

Expiration and Refresh

Access tokens have a limited lifespan. Most tokens expire after 60 minutes, though this may vary by configuration. If your application requires continuous access without user reauthentication, you should request a refresh token.

• Refresh tokens are only issued when the offline_access scope is included
• A refresh token allows your system to request a new access token without repeating the full authorization flow
• Refresh tokens have a longer lifespan and should also be secured and rotated periodically

Token Inspection and Claims

You can inspect an issued token using the /userinfo endpoint. This helps validate the current session and confirm that the appropriate scopes and roles are assigned.

The response typically includes:

• sub: Unique identifier for the authorized user or system
• scope: List of active scopes
• fhirUser: FHIR resource reference for the user (if applicable)
• token_type: Usually Bearer
• exp: Expiration timestamp (Unix format)

Token inspection is useful during debugging or when implementing conditional logic based on scopes or user role.