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

Authorization

How an application obtains an access token using SMART App Launch 2.0.0, with PKCE required on every flow.

Maximus implements SMART App Launch 2.0.0 on top of OAuth 2.0 and OpenID Connect. Two launch modes are supported: standalone launch, where the user starts in your application, and EHR launch, where the user starts inside Maximus EHR.

Discovery

Do not hard-code endpoints. Fetch the SMART configuration and read them from it, so your application keeps working if an endpoint moves.

GEThttps://fhir.maximus.care/api/r4/.well-known/smart-configuration
{
  "issuer": "https://apiauth.maximus.care",
  "authorization_endpoint": "https://apiauth.maximus.care/connect/authorize",
  "token_endpoint": "https://apiauth.maximus.care/connect/token",
  "introspection_endpoint": "https://apiauth.maximus.care/connect/introspect",
  "revocation_endpoint": "https://apiauth.maximus.care/connect/revocation",
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "code_challenge_methods_supported": ["S256"],
  "capabilities": ["launch-ehr", "launch-standalone", "permission-v1", "permission-v2", "..."]
}

Standalone launch

The user begins in your application. You ask for a patient context and Maximus presents a patient selection screen after authentication.

  1. Generate a PKCE code_verifier and its S256 code_challenge.
  2. Generate a random state and store it against the user's session.
  3. Redirect the user to the authorization endpoint.
  4. Receive the authorization code at your registered redirect URI, and verify state.
  5. Exchange the code for an access token.

Authorization request

GEThttps://apiauth.maximus.care/connect/authorize
ParameterData typeRequiredValue
response_typestringRequiredcode
client_idstringRequiredYour registered client identifier
redirect_uriuriRequiredMust match a registered URI exactly
scopestringRequiredSpace-delimited. See supported scopes
statestringRequiredRandom, single-use, verified on return
auduriRequiredhttps://fhir.maximus.care/api/r4
code_challengestringRequiredBase64url-encoded SHA-256 of the verifier
code_challenge_methodstringRequiredS256
launchstringEHR launch onlyThe opaque launch identifier handed to your app by the EHR
GET https://apiauth.maximus.care/connect/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20fhirUser%20launch%2Fpatient%20patient%2F*.rs%20offline_access
  &state=9a8b7c6d5e4f
  &aud=https%3A%2F%2Ffhir.maximus.care%2Fapi%2Fr4
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Authorization response

On approval the user is redirected back with a code. Verify state before doing anything else.

https://app.example.com/callback?code=abc123...&state=9a8b7c6d5e4f

EHR launch

The user starts inside Maximus EHR and launches your application from it. Maximus calls your registered launch URL with two parameters:

ParameterData typeMeaning
issuriThe FHIR service base URL. Use it to fetch the SMART configuration.
launchstringAn opaque identifier carrying the launch context. Pass it back unchanged on the authorization request.

The flow is otherwise identical to standalone launch, with two differences: include the launch parameter and the launch scope, and omit launch/patient — the patient context comes from the EHR, so no picker is shown.

Validate the issuer

Treat iss as untrusted input. Confirm it matches the Maximus service base URL you expect before sending any token to it. An attacker who can trigger a launch with a hostile iss could otherwise collect your tokens.

Token request

POSThttps://apiauth.maximus.care/connect/token
ParameterData typeRequiredValue
grant_typestringRequiredauthorization_code
codestringRequiredThe code just received
redirect_uriuriRequiredThe same URI used on the authorization request
code_verifierstringRequiredThe original PKCE verifier
client_idstringPublic clientsRequired when no client authentication is used

Confidential clients authenticate with HTTP Basic, sending base64(client_id:client_secret) in the Authorization header.

curl -X POST "https://apiauth.maximus.care/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic <base64 client_id:client_secret>" \
  -d "grant_type=authorization_code" \
  -d "code=abc123..." \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Token response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid fhirUser launch/patient patient/*.rs offline_access",
  "id_token": "eyJhbGciOi...",
  "refresh_token": "8xLOxBtZp8...",
  "patient": "example-patient",
  "need_patient_banner": false,
  "smart_style_url": "https://fhir.maximus.care/api/r4/smart-style-url"
}
FieldData typeMeaning
access_tokenstringSend as Authorization: Bearer on every API call
token_typestringAlways Bearer
expires_inintegerAccess token lifetime in seconds. Authoritative — do not assume a fixed value
scopestringThe scopes actually granted. May be narrower than requested
id_tokenstringPresent when openid was granted. A signed JWT identifying the user
refresh_tokenstringPresent when offline_access was granted. See refresh tokens
patientstringThe patient context id, when a patient scope was granted
need_patient_bannerbooleanWhether your app should display its own patient banner
smart_style_urluriStyling hints for embedded apps
Always check the granted scope

The scope in the token response is what you were actually granted, which may be less than you asked for. A user may narrow consent. Read it and degrade gracefully rather than assuming every requested scope was approved.

Backend services

For server-to-server access with no user present — bulk export, for example — use the client_credentials grant with system/ scopes. The client must be confidential.

curl -X POST "https://apiauth.maximus.care/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic <base64 client_id:client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=system/Patient.rs system/Observation.rs"

Token introspection

Resource servers and authorized clients may inspect a token at the introspection endpoint, per RFC 7662.

POSThttps://apiauth.maximus.care/connect/introspect

The caller authenticates with its own client credentials; the token to inspect is sent in the token parameter. Introspection is an access-controlled capability and is granted on request — it is not open to every registered client.

curl -X POST "https://apiauth.maximus.care/connect/introspect" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic <base64 client_id:client_secret>" \
  -d "token=eyJhbGciOi..."
{
  "active": true,
  "scope": "patient/*.rs",
  "client_id": "mx_...",
  "sub": "...",
  "patient": "example-patient",
  "exp": 1794831600
}
Base64 padding

The Authorization: Basic value must be correctly padded base64. Some tools omit trailing = characters, which produces a 401 with no further detail. The encoded string length must be a multiple of four.

Revocation

Tokens may be revoked at the revocation endpoint. Revoking a refresh token also invalidates access tokens derived from it.

POSThttps://apiauth.maximus.care/connect/revocation

Authorization errors

ErrorMeaningWhat to do
invalid_requestA required parameter is missing or malformedCheck the parameter table above
invalid_clientClient authentication failedCheck the client id, secret and base64 padding
invalid_grantThe code or refresh token is invalid, expired or already usedRestart the authorization flow
unauthorized_clientThis client may not use this grant typeCheck the registered grant types
invalid_scopeA requested scope is unknown or not permitted for this clientCheck supported scopes
access_deniedThe user declined authorizationHandle gracefully; do not retry automatically

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.