Maximus FHIR API
ONC §170.315(g)(10)

Refresh tokens

How refresh tokens are requested, issued, rotated, stored and revoked — including the method by which an initial refresh token is securely issued to a native application.

A refresh token lets an application obtain a new access token without the user authorizing again. This page documents how Maximus issues refresh tokens, and in particular how an initial refresh token is issued securely to a native application — a disclosure required by the §170.315(g)(10) Certification Companion Guide.

Requesting a refresh token

Include the offline_access scope in the authorization request. If the user approves, the token response contains a refresh_token.

&scope=openid fhirUser patient/*.rs offline_access
Online versus offline

Maximus issues refresh tokens under offline_access, which survives the end of the user's session. Request it only if your application genuinely needs to work while the user is away; otherwise omit it and let the access token expire.

Secure issuance to native applications

A native application is a public client: it runs on the user's own device and cannot hold a client secret, because anything shipped inside the binary can be extracted. Maximus therefore does not rely on a secret to establish that the initial refresh token is going to the genuine application. Four controls do that work together.

1. PKCE on every authorization code exchange

Proof Key for Code Exchange (RFC 7636) is mandatory, with code_challenge_method=S256. The plain method is not accepted and the authorization server advertises only S256.

  • Before redirecting, the app generates a high-entropy random code_verifier.
  • It sends only the SHA-256 hash of that value, as code_challenge.
  • At the token endpoint it must present the original code_verifier.

An attacker who intercepts the authorization code cannot redeem it, because the verifier never left the device. This is what protects the initial refresh token issuance in the absence of a client secret.

code_verifier  = dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
code_challenge = BASE64URL( SHA256( code_verifier ) )
               = E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

2. Exact redirect URI matching

The redirect URI is registered in advance and matched exactly — scheme, host, port and path. A code is only ever delivered to a registered destination. Native applications should register a claimed HTTPS URI where the platform supports it, because the operating system verifies ownership against your domain and prevents another application from claiming the same URI.

3. Authorization in the system browser

Per RFC 8252, the authorization request must be made in the system browser or an in-app browser tab, never an embedded web view. The host application cannot read credentials entered in the system browser, and existing session cookies are reused safely.

4. TLS 1.2 or above on every leg

The refresh token is only ever transmitted over TLS 1.2 or above. Connections below that are refused at the handshake. See security and TLS.

Summary of the disclosed method

The initial refresh token is issued to a native application through the OAuth 2.0 authorization code grant, secured with mandatory S256 PKCE, exact pre-registered redirect URI matching, system-browser authorization per RFC 8252, and TLS 1.2 or above — without requiring the native application to hold a client secret.

Using a refresh token

POSThttps://apiauth.maximus.care/connect/token
ParameterData typeRequiredValue
grant_typestringRequiredrefresh_token
refresh_tokenstringRequiredThe refresh token you hold
scopestringOptionalA subset of the originally granted scopes. Omit to retain them all
client_idstringPublic clientsRequired when no client authentication is used
curl -X POST "https://apiauth.maximus.care/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=8xLOxBtZp8..." \
  -d "client_id=YOUR_CLIENT_ID"

Lifetime and rotation

PropertyBehaviour
Access token lifetimeReturned as expires_in on every token response. Read it rather than assuming a fixed value.
Refresh token lifetimeConfigured per client. The platform default is 90 days from issuance.
RotationA refresh exchange may return a new refresh_token. If one is returned, replace the stored value immediately and discard the old one.
Scope narrowingA refresh may request a subset of the granted scopes, never a superset.
Handle expiry, do not pre-empt it

Refresh when a call returns 401 Unauthorized, or shortly before expires_in elapses. If the refresh itself fails with invalid_grant, the refresh token is spent or revoked — send the user through authorization again.

Storing refresh tokens

A refresh token is a long-lived credential for protected health information. Store it accordingly.

PlatformWhere to store it
iOSKeychain, with an accessibility class that requires the device to be unlocked
AndroidEncryptedSharedPreferences or the Android Keystore
DesktopThe operating system credential store — DPAPI, Keychain or Secret Service
ServerEncrypted at rest, with access restricted to the service that needs it
Browser SPAAvoid. Prefer a backend-for-frontend that holds the token server-side

Revocation

Revoke a refresh token when the user signs out or removes the integration. Revoking a refresh token also invalidates the access tokens derived from it.

curl -X POST "https://apiauth.maximus.care/connect/revocation" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=8xLOxBtZp8..." \
  -d "token_type_hint=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID"

Patients may also revoke an application's access from within the Maximus patient portal. When that happens your next refresh returns invalid_grant; treat it as a signal to stop, not to retry.

Last updated 18 November 2026

Maximus EHR — documentation published for the ONC Health IT Certification Program.

See the API terms and conditions. Where this documentation and the Maximus EHR listing on the ONC Certified Health IT Product List differ, the CHPL listing governs.

© 2026 MaxRemind Inc. All rights reserved.