Search
K
< Back

Overview

Health Gorilla APIs authenticate clients using OAuth 2.0 and authorize access to clinical data through short-lived credentials exchanged at runtime. The model separates authentication (proving client identity) from authorization (granting scoped access to APIs) to support secure access across sandbox and production environments.

Authentication begins with a JWT assertion generated by the client. The assertion is presented to the OAuth token endpoint and exchanged for an OAuth access token. The access token is then included in the Authorization: Bearer header for all downstream API calls.

Key Concepts

Health Gorilla’s authentication model relies on a small set of core components that work together to establish identity, exchange credentials, and authorize access to APIs. Understanding the role and lifecycle of each component is essential to generating valid tokens and avoiding common integration errors.

  • JWT assertion: A short-lived authorization credential generated by the client and used only to authenticate to the OAuth token endpoint.
  • OAuth access token: A bearer token returned by the token endpoint and required for all API requests.
  • Scopes: Define permitted actions and data access and are validated during token exchange scope definitions and enforcement details are documented in the API Reference.
  • Environments: Sandbox and production use different token URLs, audience values, and base FHIR URLs.

Important Statements

Several non-negotiable rules govern how authentication credentials are generated and used. These statements describe conditions that apply to all integrations and explain why certain seemingly valid usage patterns will fail.

  • JWT assertions are not OAuth access tokens and cannot be used to call FHIR APIs directly.
  • An OAuth access token is required for every downstream API request.
  • JWT assertions are short-lived and must be regenerated when expired.
  • Token exchange parameters and audience values must match the target environment.

Supported OAuth Flows

Health Gorilla supports multiple OAuth token exchange patterns to accommodate different integration models. Each flow uses a JWT assertion but differs in how the assertion is presented and when the flow is appropriate.

  • JWT Bearer flow: Exchanges a JWT assertion for an access token.
  • Client Credentials flow: Uses a JWT assertion as a client assertion within the client credentials grant.

Detailed request parameters, cURL examples, and response formats are documented on the OAuth Token Exchange page.

Common Pitfalls

Authentication issues most often stem from misunderstandings about credential types, environment targeting, or OAuth parameters. The scenarios below reflect common onboarding and integration mistakes.

  • Treating the value copied from jwtoken.html as an access token.
  • Using an assertion generated for one environment against another environment’s token URL.
  • Reusing expired assertions.
  • Mixing parameters from different OAuth flows in a single request.