Guides
Subscribe to Release Notes
  1. Identity & Access
  2. OAuth 2.0

Authorization Flows

Health Gorilla supports multiple OAuth 2.0 grant types to support different integration models. The appropriate flow depends on whether the integration involves an authenticated end user or operates as a trusted system-to-system connection.

Each authorization flow results in the issuance of an access token. The access token represents the intersection of:

  • The scopes assigned to the client during registration
  • The permissions of the authenticated user (when applicable)
  • The tenant context associated with the request

Selecting the correct flow is essential to ensure proper enforcement of security and authorization boundaries.

Supported Grant Types

  • Client Credentials Grant
  • Authorization Code Grant
  • JWT Bearer Token Grant
  • Implicit Grant (if enabled for your integration)

Choosing the Appropriate Flow

Client Credentials Grant

The Client Credentials Grant is intended for server-to-server integrations where no user is involved.

Use this flow when:

  • The integration operates as a backend service
  • No user context is needed for the request

In this flow, the client authenticates directly at the token endpoint with its client_id and client_secret.

Authorization Code Grant

The Authorization Code Grant is intended for integrations that involve an authenticated user.

Use this flow when:

  • The application is a confidential web or server-based application
  • User-level permissions must be evaluated within a tenant context
  • An interactive login experience is required

This flow consists of:

  1. Redirecting the user to the authorization endpoint
  2. Receiving an authorization code at the registered callback URL
  3. Exchanging the authorization code for an access token at the token endpoint

The issued access token reflects both the client’s registered scopes and the authenticated user’s permissions within the tenant.

This is the recommended flow for most user-facing integrations.

JWT Bearer Token Grant

The JWT Bearer Grant is intended for non-interactive integrations that act as a specific Health Gorilla user, without an interactive login.

Use this flow when:

  • The integration operates as a backend service
  • A trusted relationship exists between systems
  • Access is performed as a Health Gorilla user identified in the JWT, rather than through an interactive user session

In this flow:

  • The client generates a signed JWT assertion
  • The JWT is exchanged directly for an access token at the token endpoint
  • The resulting token reflects the scopes assigned to the client during registration

JWT assertions must:

  • Be signed using HS256 with the client_secret
  • Include required claims defined in the OAuth JWT Bearer specification
  • Include an aud claim set to the Health Gorilla token endpoint (/oauth/token). The exact audience value must match the token endpoint URL configured for your environment.

Although no interactive login occurs, the access token is issued for the user named in the JWT sub claim, and that user must belong to an organization the client is registered for.

Implicit Grant

The Implicit Grant may be used for public client applications that cannot securely store a client_secret.

In this flow:

  • The access token is returned directly in the redirect URI fragment
  • No refresh token is issued
  • The returned token should be validated using /oauth/info

New integrations should use Authorization Code Grant when possible. The Implicit Grant is generally reserved for legacy or constrained environments.

Authorization Endpoint

All interactive flows begin at:

GET /oauth/authorize

Common request parameters include:

  • response_type
  • client_id
  • redirect_uri
  • scope
  • state

Extended authentication parameters may be provided in supported user-interactive scenarios to streamline the authorization experience:

  • hg_user_first_name
  • hg_user_last_name
  • hg_user_dob (format YYYYMMDD)
  • hg_user_email

Go to API Reference > OAuth 2.0 Authentication for complete parameter definitions and request formats.

Token Exchange

Access tokens are issued by:

POST /oauth/token

During token issuance:

  • The granted scope cannot exceed the scopes assigned to the client during registration
  • For Authorization Code Grant, scope is further limited by the original authorization request
  • Scope cannot be expanded during refresh

Access tokens are time-limited and must be refreshed if a refresh token was issued for the applicable flow or reissued through the appropriate authorization flow when expired.

Go to API Reference > OAuth 2.0 Authentication for required parameters, response formats, and error codes.

Error Handling Model

OAuth-related errors may occur:

  • At the authorization endpoint (returned as redirect parameters)
  • At the token endpoint (returned as JSON error responses, commonly HTTP 400, depending on the error condition)
  • When calling protected APIs (returned as HTTP 401 or 403 responses)

An HTTP 401 response indicates that the token is invalid or expired.

An HTTP 403 response indicates that the token lacks the required scope.

Understanding where an error originates is essential when troubleshooting integration issues.

Updated 1 day ago