OAuth Flows

Health Gorilla supports multiple OAuth 2.0 grant types to accommodate different integration scenarios, including backend systems, user-facing applications, and SMART-on-FHIR use cases. Each flow results in an access token that can be used to access FHIR resources.

Client Credentials (server-to-server)

Used for backend system integrations where there is no end-user interaction. The client authenticates directly using its credentials.

Token Request

POST /oauth/token
Content-Type: application/json
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Example Response

{  
  "access_token": "access_token_value",  
  "token_type": "Bearer",  
  "expires_in": 3600,  
  "scope": "user/."  
}

JWT Bearer Token Grant

Used for secure, non-interactive system-to-system access. The client signs a JWT using its secret and exchanges it for an access token.

Required JWT Claims

Claim	Description
`iss`	Issuer — must match the client identifier (e.g., your registered app URL)
`sub`	Subject — the user or system being authenticated (provided by Health Gorilla)
`aud`	Audience — must be `https://www.healthgorilla.com/oauth/token`
`exp`	Expiration time — UNIX timestamp after which the JWT is no longer valid
`nbf`	Not Before — JWT is not valid before this UNIX timestamp
`iat`	Issued At — time the JWT was issued (UNIX timestamp)

Note: JWT must be signed with the client_secret using HS256.

Token Request

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id={client_id}
&scope=user/*.*
&assertion={your_signed_jwt}

Example Response

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

Authorization Code Grant (User-Facing Applications)

Used for applications where users log in and authorize access via browser redirect. This is the recommended flow for web and mobile apps.

Step 1: Authorization Request

GET /oauth/authorize?
  response_type=code
  &client_id=your_client_id
  &redirect_uri=https://yourapp.com/callback
  &scope=place_orders
  &state=xyz

Optional: Include additional user-identifying fields such as hg_user_first_name, hg_user_email, or hg_user_dob.

Step 2: Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=auth_code_value
&client_id=your_client_id
&client_secret=your_client_secret
&redirect_uri=https://yourapp.com/callback

Example Response

{
  "access_token": "access_token_value",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_value",
  "scope": "place_orders"
}

Authorization Endpoints

Action	Endpoint
Authorization Request	`https://api.healthgorilla.com/oauth/authorize`
Token Exchange	`https://api.healthgorilla.com/oauth/token`