Token Lifecycle

Access tokens issued by the Health Gorilla authorization server are time-limited credentials used to access protected APIs. Proper handling of token issuance, expiration, refresh, and revocation is required to maintain secure and reliable integrations.

Access Token Issuance and Expiration

Access tokens are issued by:

POST /oauth/token

Each access token:

• Is bound to the scopes granted at issuance
• Is associated with a specific client and tenant context
• Has a defined lifetime (expires_in)
• Must be presented with each request to protected APIs

Access tokens expire after their configured lifetime. Once expired, the token can no longer be used to access protected endpoints.

Token Lifetime and Expiration Handling

When an access token expires:

• API requests using the expired token return 401 Unauthorized
• The client must either refresh the token (if a refresh token was issued) or initiate a new authorization flow

Clients should track token expiration using the expires_in value returned during token issuance and proactively refresh tokens when appropriate.

Conditions Requiring Re-Authorization

A full re-authorization flow may be required when:

• No refresh token was issued for the flow
• The refresh token has expired or been invalidated
• The client’s assigned scopes have changed
• Client credentials have been rotated or invalidated
• The authorization server has revoked existing tokens for security or administrative reasons

In these cases, the client must repeat the appropriate authorization flow to obtain a new access token.

Refresh Token Issuance and Limitations

Refresh tokens may be issued for certain grant types (for example, Authorization Code Grant).

Refresh tokens:

• Are used to obtain new access tokens without repeating the full authorization flow
• Are bound to the originally granted scope
• Cannot be used to expand scope
• May have their own expiration or revocation policies

If a refresh token is not issued for a given flow (for example, Implicit Grant), the client must re-authorize when the access token expires.

Refresh Token Request

To obtain a new access token using a refresh token:

POST /oauth/token

With:

grant_type=refresh_token

The newly issued access token:

• Reflects the same scope originally granted
• Does not expand permissions

Go to API Reference > OAuth 2.0 Authentication for complete request parameters and response formats.

Token Validation

Access tokens may be validated using:

GET /oauth/info

Token validation should confirm:

• The token is active and not expired
• The client_id in the response matches the expected client
• The returned scope matches the expected permissions

Validation is particularly important when tokens are received through redirect-based flows.

Go to API Reference > OAuth 2.0 Authentication for response structure details.

Token Revocation

Tokens may be revoked using:

GET /oauth/cancel

Revocation:

• Invalidates the specified access token
• Also invalidates the associated refresh token (if applicable)
• Returns 200 OK on successful revocation

A successful revocation response does not indicate whether the token was previously valid, only that it is no longer usable after the request.

After revocation, the token can no longer be used to access protected APIs.

Token Invalidation Scenarios

Tokens may become invalid due to:

• Access token expiration
• Manual revocation
• Refresh token expiration or revocation
• Client credential rotation
• Scope configuration changes
• Authorization server security enforcement actions

When a token is invalid:

• Protected API calls return 401 Unauthorized
• The client must refresh or re-authorize as appropriate

Proper token lifecycle management ensures secure access to Health Gorilla APIs and reduces authentication-related errors in production integrations.