User Identity & API Versioning

OAuth sessions in Health Gorilla establish both authorization context and, when applicable, user identity context. This page describes how user identity information is exposed through OAuth and how API versioning can be controlled within an OAuth session.

User Identity Endpoint

User identity information may be retrieved using:

GET /oauth/userinfo

The /oauth/userinfo endpoint returns information about the authenticated user associated with the access token.

This endpoint applies to flows where a user identity is present (for example, Authorization Code Grant). For client-only or system-to-system flows where no user context exists, user identity information may not be available.

A valid access token is required to call this endpoint. Access to user identity information is subject to the scopes and permissions associated with the token.

Go to API Reference > OAuth 2.0 Authentication for the complete response schema.

User Identity Data Exposed

The /oauth/userinfo response may include:

Unique user identifier (uid)
First and last name
Administrative role
NPI (if applicable)
Email address and verification status
Organization information associated with the user

The exact fields returned depend on the authenticated user, the scopes granted, and the tenant context associated with the token.

User identity data reflects the state of the user at the time the token is evaluated. It does not override scope-based or tenant-based access control.

Administrative Role and Tenant Context

When an OAuth flow involves an authenticated user, the issued access token is associated with:

The client application
The tenant context
The authenticated user

The user’s administrative role within the tenant influences what actions are permitted when calling protected APIs.

OAuth scopes define which APIs may be accessed.
User roles define what operations are permitted within the tenant.

A valid scope does not grant permissions beyond the user’s assigned role.

OAuth Session and Tenant Context

Each access token is bound to a specific tenant context.

For user-interactive flows:

The tenant context is determined by the authenticated user.
API requests are evaluated within that tenant.

For system-to-system flows:

The tenant context is associated with the registered client configuration.
If a JWT Bearer flow includes a subject (sub) representing a user, tenant context and permissions may also be evaluated based on that subject, depending on configuration.

Tokens do not grant cross-tenant access unless explicitly configured.

REST API Version Targeting

Health Gorilla supports binding a specific REST API version to an OAuth session.

A client may request a specific API version during token issuance using:

hg_rest_api_version=<version>

If specified during token issuance:

The requested API version is associated with the issued access token.
Subsequent API calls made with that token use the specified version.

Go to API Reference > OAuth 2.0 Authentication for parameter details.

Default API Version Behavior

If hg_rest_api_version is not specified:

The default API version configured for the target environment is applied.

The default version is defined by environment configuration and platform versioning policy.

Unsupported Version Behavior

If an unsupported API version is requested during token issuance:

The token request fails.
An error response is returned indicating that the supplied API version is not supported.

Clients should validate version compatibility prior to requesting a specific API version.