Search
K
< Back

Refresh Token

Access tokens issued during the SMART on FHIR authorization flow are valid for a limited time. When a token expires, the viewer cannot retrieve additional FHIR data unless your application obtains a new access token. To maintain session continuity, Health Gorilla may issue a refresh token alongside the original access token, depending on your application’s configuration.

The viewer does not persist any data between sessions. If an access token expires during a session, the viewer displays an authorization error or session timeout message. To recover, users must relaunch the viewer unless your application supports automatic token refresh.

When to Use a Refresh Token

Use a refresh token to maintain access without requiring users to reauthenticate:

  • When the original access token has expired (for example, after receiving a 401 Unauthorized error)
  • When your application supports persistent sessions or multiple viewer launches
  • When Health Gorilla has issued a refresh token (typically for confidential clients)

Not all application types receive a refresh token. Public clients, single-use sessions, or browser-based apps may be excluded.

To request a new access token

  1. Monitor for token expiration by tracking the expires_in value from the original token response or handling 401 errors during API calls.
  2. From your backend, send a POST request to: https://api.healthgorilla.com/oauth2/token and set the Content-Type header to application/x-www-form-urlencoded.
  3. Include the following form parameters:
  • grant_type=refresh_token
  • refresh_token=YOUR_REFRESH_TOKEN
  • client_id=YOUR_CLIENT_ID
  • client_secret=YOUR_CLIENT_SECRET (if applicable)
  1. Parse the response. If successful, Health Gorilla returns a new access_token and optionally a new refresh_token.
  2. Replace the stored token values in your application and resume FHIR API access using the new credentials.

Note: If a new refresh token is returned, you must store it securely and discard the previous one.