Using Access Tokens

All requests to protected Health Gorilla APIs must include a valid OAuth access token. Access tokens are bearer tokens and must be transmitted securely with each API request.

Passing Access Tokens

Access tokens must be sent using the Authorization header:

Authorization: Bearer <access_token>

The bearer token grants access to protected resources within the scope and tenant context associated with the token.

The Authorization header method is the required and recommended mechanism for transmitting access tokens in production integrations.

Query Parameter Usage

Access tokens should not be transmitted in URLs for production integrations.

If a query parameter mechanism is enabled for a specific integration, it is intended for limited or legacy scenarios and is not recommended for general use.

Transmitting tokens in URLs may:

Expose tokens in logs or browser history
Increase the risk of token leakage
Create unintended persistence in monitoring systems

For security reasons, use the Authorization header when calling Health Gorilla APIs.

HTTP Status Behavior

When calling protected endpoints, the HTTP status code indicates whether the access token is valid and authorized for the requested operation.

401 Unauthorized

A 401 Unauthorized response indicates that the token is invalid, expired, or otherwise not accepted by the authorization server.

Common causes include:

An expired access token
A malformed or unrecognized token
A token that has been revoked

Error identifiers such as expired_token or invalid_token may be returned depending on the endpoint and error condition.

When a 401 response is returned:

Attempt to refresh the token if a refresh token is available
If refresh is not possible or fails, initiate a new authorization flow

403 Forbidden

A 403 Forbidden response indicates that the token is valid but does not include the required scope or the authenticated user lacks necessary permissions.

Common cause:

insufficient_scope – The access token does not include the scope required for the requested API

In this case:

Verify that the client has been assigned the required scope
Confirm that the user has appropriate permissions within the tenant
Re-authorize if broader access is required

Handling Expired Tokens and Retry Patterns

Clients should anticipate token expiration and implement appropriate retry logic.

Recommended pattern:

Track the token’s expiration time using the expires_in value returned during issuance
Proactively refresh the token before expiration when possible
If a request fails with 401 Unauthorized, refresh the token (if available) and retry the request once
If refresh fails, initiate a full authorization flow

Clients should avoid infinite retry loops and ensure that repeated authentication failures are surfaced for investigation.

Proper handling of access tokens reduces authentication-related failures and improves the reliability of production integrations.