OAuth Token Exchange

OAuth access tokens authorize your system to call Health Gorilla APIs. Tokens are issued by the OAuth 2.0 token endpoint after a successful exchange using a short-lived JWT assertion. All downstream API requests require a valid access token.

Health Gorilla supports two OAuth 2.0 token exchange flows. Each flow uses a JWT assertion but differs in how the assertion is presented and when the flow applies.

Token Endpoint

Token exchange occurs against an environment-specific endpoint. The endpoint you use must match the audience (aud) value in your JWT assertion.

Sandbox environment: https://sandbox.healthgorilla.com/oauth/token
Production environment: https://api.healthgorilla.com/oauth/token

JWT Bearer Flow

The JWT Bearer flow exchanges a JWT assertion directly for an OAuth access token. This flow is commonly used for system-to-system integrations where the client authenticates without additional client secrets in the request body.

Required Parameters

The token request must include the following parameters:

grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion: YOUR_JWT_ASSERTION
scope: patient360 user/.

JWT Bearer Token Request Example

curl -X POST "https://sandbox.healthgorilla.com/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
-d 'assertion=YOUR_JWT_ASSERTION' \
-d 'scope=patient360 user/*.*'

Response Example

  {
  "access_token": "ACCESS_TOKEN_VALUE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "patient360 user/*.*"
}

Client Credentials Flow

The Client Credentials flow uses a JWT assertion as a client assertion within the OAuth 2.0 client credentials grant. This flow is typically used when your organization requires explicit client authentication semantics as part of the token request.

Required Parameters

The token request must include the following parameters:

grant_type: client_credentials
client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion: YOUR_JWT_ASSERTION scope: patient360 user/.

Client Credentials Token Request Example

curl -X POST "https://sandbox.healthgorilla.com/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials' \
-d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
-d 'client_assertion=YOUR_JWT_ASSERTION' \
-d 'scope=patient360 user/*.*'

Response Example

{
  "access_token": "ACCESS_TOKEN_VALUE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "patient360 user/*.*"
}

Using The Access Token

OAuth access tokens must be included in the Authorization header for all API requests. The token value determines permitted resources and operations based on assigned scopes.

curl -X GET "https://sandbox.healthgorilla.com/fhir/R4/Patient/12345" \
-H "Authorization: Bearer ACCESS_TOKEN_VALUE" \
-H "Accept: application/fhir+json"

Common Token Exchange Errors

Token exchange failures typically result from mismatched parameters, expired assertions, or incorrect environment targeting.

Common causes include:

Using a JWT assertion directly in an API request instead of exchanging it for an access token
Setting the aud claim to a different environment than the token URL
Reusing an expired JWT assertion
Mixing parameters from the JWT Bearer and Client Credentials flows
Using an incorrect grant_type value

Correcting the request parameters and regenerating the JWT assertion resolves most token exchange issues.