Assertions vs Tokens
Health Gorilla’s authentication flow uses two distinct credential types that serve different purposes and are not interchangeable. Confusing these credentials is the most common cause of authentication failures during onboarding and early integration.
JWT assertions are generated by the client and used only to authenticate to the OAuth token endpoint. Access tokens are issued by Health Gorilla’s OAuth service and are required for all downstream API calls.
Conceptual Differences
JWT assertions and OAuth access tokens exist at different stages of the authentication process and have different lifecycles, audiences, and usage rules.
| Item | Generated By | Used For | Lifetime |
|---|---|---|---|
| JWT Assertion | jwtoken.html or client-side signing logic | Authenticate to /oauth/token | Minutes |
| Access Token | /oauth/token | Call FHIR and other HG APIs | Hours |
JWT Assertions
JWT assertions are short-lived authorization credentials created and signed by the client. They establish client identity and are presented only to the OAuth token endpoint.
Key characteristics:
- Generated by
jwtoken.htmlor equivalent client logic - Signed using the client’s private key
- Intended for token exchange only
- Expire quickly and cannot be reused after expiration
JWT assertions are never sent directly to FHIR APIs.
OAuth Access Tokens
OAuth access tokens are bearer tokens issued by Health Gorilla after a successful token exchange. They represent granted authorization and must be included in all API requests.
Key characteristics:
- Returned by
/oauth/token - Included in requests as
Authorization: Bearer <access_token> - Valid for a longer duration than assertions
- Scoped to permitted resources and operations
All downstream API calls require a valid access token.
Common Sources of Confusion
Several UI and workflow details frequently lead to incorrect usage.
- The
jwtoken.htmlinterface labels its button “Copy Token”, but the copied value is a JWT assertion, not an access token. - Pasting a JWT assertion directly into a FHIR request results in an
invalid_tokenerror. - A successful assertion generation does not indicate that authentication is complete; a token exchange is still required.
Required Sequence
Authentication always follows this order:
- Generate a JWT assertion
- Exchange the assertion at
/oauth/token - Receive an OAuth access token
- Call APIs using the access token
Skipping or reordering these steps causes authentication to fail.
Explicit Warnings
- JWT assertion ≠ OAuth access token
jwtoken.htmloutputs an assertion only- Access tokens are obtained only from
/oauth/token - Assertions must be exchanged before any API call
Failure to follow this separation results in predictable and avoidable authentication errors.