Scopes & Access Control

OAuth scopes define the APIs and operations a client application is permitted to access. Scopes are assigned during client registration and are enforced at the time an access token is issued.

An issued access token reflects the intersection of:

• The scopes assigned to the client during registration
• The scopes requested during authorization (if applicable)
• The permissions of the authenticated user within the tenant

Scopes control API-level access. User roles control what actions are permitted within a tenant context. Both layers must be satisfied for a request to succeed. Scopes do not grant access outside the tenant context associated with the token.

Scope Assignment

Scopes are configured at registration time and are associated with a specific client_id.

Scopes:

• Define which APIs the client application may invoke
• Are limited to those explicitly approved during onboarding
• Cannot be self-assigned or dynamically expanded by the client

If additional API access is required, scope changes must be requested through Health Gorilla.

Requesting Scopes

Scopes are requested as a space-delimited list during the authorization request.

Example format:

scope=scope1 scope2 scope3

A client may request only scopes that were assigned during registration. If a requested scope was not assigned, the authorization request will fail.

The authorization server may issue a token with a subset of the requested scopes.

Default Scope Behavior

If the scope parameter is omitted during authorization:

• The default scopes assigned to the client during registration are applied

The token issued will not include scopes beyond those configured for the client.

Scope Limitations During Token Exchange

During the token exchange process:

• The granted scope cannot exceed the scopes assigned to the client at registration
• For Authorization Code Grant, the granted scope cannot exceed the scope requested in the original authorization request
• Scope cannot be expanded during token exchange

If a requested scope is invalid or exceeds the client’s assigned permissions, the token request will fail.

Scope Behavior During Refresh

When a refresh token is used to obtain a new access token:

• The scope of the refreshed token is limited to the scope originally granted
• Scope cannot be expanded during refresh

If broader access is required, a new authorization flow must be initiated.

OAuth Scope vs. User-Level Permissions

OAuth scopes and user permissions serve different purposes:

• Scopes determine which APIs the client application is allowed to call
• User-level permissions determine what data and operations are permitted within a tenant

For user-interactive flows, both scope and user permissions are evaluated. A valid scope alone does not guarantee that a request will succeed if the authenticated user lacks required permissions within the tenant.

Example Scopes

Examples of scopes may include:

• create_users
• Other API-specific scopes assigned during registration

The exact scopes available to a client are defined at registration time and vary by integration.

Common Authorization Failures

Authorization-related failures may include:

• insufficient_scope – The access token does not include the scope required for the requested API
• invalid_client – The client authentication failed or the client_id is not recognized
• invalid_grant – The provided authorization code, refresh token, or assertion is invalid, expired, or does not match the client

Failures may occur at the authorization endpoint, token endpoint, or when calling protected APIs, depending on where the validation fails.