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
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.
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
| Parameter | Data type | Required | Value |
|---|---|---|---|
grant_type | string | Required | refresh_token |
refresh_token | string | Required | The refresh token you hold |
scope | string | Optional | A subset of the originally granted scopes. Omit to retain them all |
client_id | string | Public clients | Required 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
| Property | Behaviour |
|---|---|
| Access token lifetime | Returned as expires_in on every token response. Read it rather than assuming a fixed value. |
| Refresh token lifetime | Configured per client. The platform default is 90 days from issuance. |
| Rotation | A refresh exchange may return a new refresh_token. If one is returned, replace the stored value immediately and discard the old one. |
| Scope narrowing | A refresh may request a subset of the granted scopes, never a superset. |
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.
| Platform | Where to store it |
|---|---|
| iOS | Keychain, with an accessibility class that requires the device to be unlocked |
| Android | EncryptedSharedPreferences or the Android Keystore |
| Desktop | The operating system credential store — DPAPI, Keychain or Secret Service |
| Server | Encrypted at rest, with access restricted to the service that needs it |
| Browser SPA | Avoid. 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.