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.
{
"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.
- Generate a PKCE
code_verifierand itsS256code_challenge. - Generate a random
stateand store it against the user's session. - Redirect the user to the authorization endpoint.
- Receive the authorization code at your registered redirect URI, and verify
state. - Exchange the code for an access token.
Authorization request
| Parameter | Data type | Required | Value |
|---|---|---|---|
response_type | string | Required | code |
client_id | string | Required | Your registered client identifier |
redirect_uri | uri | Required | Must match a registered URI exactly |
scope | string | Required | Space-delimited. See supported scopes |
state | string | Required | Random, single-use, verified on return |
aud | uri | Required | https://fhir.maximus.care/api/r4 |
code_challenge | string | Required | Base64url-encoded SHA-256 of the verifier |
code_challenge_method | string | Required | S256 |
launch | string | EHR launch only | The 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:
| Parameter | Data type | Meaning |
|---|---|---|
iss | uri | The FHIR service base URL. Use it to fetch the SMART configuration. |
launch | string | An 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.
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
| Parameter | Data type | Required | Value |
|---|---|---|---|
grant_type | string | Required | authorization_code |
code | string | Required | The code just received |
redirect_uri | uri | Required | The same URI used on the authorization request |
code_verifier | string | Required | The original PKCE verifier |
client_id | string | Public clients | Required 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"
}
| Field | Data type | Meaning |
|---|---|---|
access_token | string | Send as Authorization: Bearer on every API call |
token_type | string | Always Bearer |
expires_in | integer | Access token lifetime in seconds. Authoritative — do not assume a fixed value |
scope | string | The scopes actually granted. May be narrower than requested |
id_token | string | Present when openid was granted. A signed JWT identifying the user |
refresh_token | string | Present when offline_access was granted. See refresh tokens |
patient | string | The patient context id, when a patient scope was granted |
need_patient_banner | boolean | Whether your app should display its own patient banner |
smart_style_url | uri | Styling hints for embedded apps |
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.
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
}
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.
Authorization errors
| Error | Meaning | What to do |
|---|---|---|
invalid_request | A required parameter is missing or malformed | Check the parameter table above |
invalid_client | Client authentication failed | Check the client id, secret and base64 padding |
invalid_grant | The code or refresh token is invalid, expired or already used | Restart the authorization flow |
unauthorized_client | This client may not use this grant type | Check the registered grant types |
invalid_scope | A requested scope is unknown or not permitted for this client | Check supported scopes |
access_denied | The user declined authorization | Handle gracefully; do not retry automatically |