Generating JWT Assertions
JWT assertions authenticate your system to Health Gorilla’s OAuth 2.0 token endpoint. Assertions are short-lived credentials generated by your organization and exchanged for OAuth access tokens, which are required for all downstream API calls.
When To Generate A JWT Assertion
JWT assertions contain short-lived timestamps and must be generated immediately before token exchange. Reusing assertions or generating them too early commonly results in authentication failures.
Generate a new JWT assertion when you are ready to request an OAuth access token.
How jwtoken.html Is Used
Health Gorilla provides jwtoken.html to help generate correctly formatted JWT assertions during onboarding and testing. The tool constructs a signed assertion using your client credentials and the selected environment.
Production integrations may generate JWT assertions programmatically, but the same claim requirements apply.
Generate A JWT Assertion
Use the following procedure to generate a JWT assertion with jwtoken.html.
- Open jwtoken.html in your browser.
- Select the target environment (sandbox or production).
- Enter your client_id.
- Verify that the token URL displayed in the tool matches the selected environment.
- Generate the JWT assertion.
- Select Copy Token to copy the generated value.
- Use the copied value as the JWT assertion when calling
/oauth/token.
The Copy Token button copies the JWT assertion only. An OAuth access token is obtained only through token exchange.
Required JWT Claims
JWT assertions must include a specific set of claims to be accepted by the OAuth 2.0 token endpoint. Each claim serves a validation purpose during token exchange.
| Claim | Required Value | Notes |
|---|---|---|
iss | YOUR_CLIENT_ID | Must match your assigned client ID |
sub | YOUR_CLIENT_ID | Do not use an email address |
aud | Token URL for the target environment | Must match exactly |
iat | Current epoch time | Issued-at timestamp |
exp | Future epoch time | Short-lived expiration |
The iss and sub claims must always match your assigned client ID. Using an email address or user identifier causes token exchange to fail.
Environment-Specific Values
JWT assertions are validated against environment-specific endpoints. The audience value must match the token URL used for exchange.
- Sandbox environment token URL and
aud: https://sandbox.healthgorilla.com/oauth/token - Production environment token URL and
aud: https://api.healthgorilla.com/oauth/token
Using a sandbox assertion against a production token URL, or vice versa, results in an authentication error.
Common Errors During Assertion Generation
Assertion-related failures are typically caused by claim mismatches or expired timestamps.
Common issues include:
- Using an email address in the sub claim
- Mismatched iss and sub values
- Incorrect aud for the target environment
- Reusing an expired assertion
- Copying a truncated assertion value from chat or email tools
Correcting these issues resolves most assertion generation errors.
Next Step
After generating a valid JWT assertion, exchange it for an OAuth access token using the OAuth token endpoint. Use the returned access token in the Authorization header for all API requests.