SMART on FHIR Developer Guide: Discovery, Launch, Scopes, Tokens and Backend Services
How SMART App Launch 2.x works end to end: discovery, EHR and standalone launch, PKCE, v1 vs v2 scopes, the token response and backend services.
By the FHIR Toolbox team, Omindra Labs · 5 min read ·
Checked against the official specifications listed under Standards and references at the end of this article.
SMART on FHIR is the authorization layer on top of FHIR's REST API. It's OAuth 2.0 and OpenID Connect, profiled for healthcare: how an app discovers a server's endpoints, how it's launched with a patient already selected, how scopes map to FHIR resources, and what extra context comes back with the token. This guide follows the SMART App Launch 2.x specification (2.0 in 2021, with 2.1 and 2.2 as later point releases). Most US EHR APIs support it because the ONC certification program requires it.
Step 1: discovery
Everything starts from the FHIR base URL. The server publishes its authorization configuration at a well-known path:
GET https://fhir.example.org/r4/.well-known/smart-configuration
{
"issuer": "https://auth.example.org",
"authorization_endpoint": "https://auth.example.org/authorize",
"token_endpoint": "https://auth.example.org/token",
"jwks_uri": "https://auth.example.org/.well-known/jwks.json",
"grant_types_supported": ["authorization_code", "client_credentials"],
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic"],
"scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "offline_access"],
"capabilities": [
"launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric",
"context-ehr-patient", "context-standalone-patient", "sso-openid-connect",
"permission-v2", "permission-patient"
]
}
capabilities tells you what the server supports before you write any code: which launch modes, whether it accepts public clients (no secret), and whether it understands v1 scopes, v2 scopes or both.
Step 2: launch
EHR launch
The user is already in the EHR with a patient open and clicks your app. The EHR opens your launch URL with two parameters:
https://app.example.com/launch?iss=https://fhir.example.org/r4&launch=xyz123
iss— the FHIR base URL. Run discovery against it, and check it against an allowlist so a malicious link can't point your app at a fake server.launch— an opaque handle to the EHR session. Send it back in the authorization request with thelaunchscope.
Standalone launch
The user opens your app directly. There's no launch parameter, so you request launch/patient and the authorization server asks the user to pick a patient (or uses the patient's own record in a patient-facing app).
Step 3: authorization request
GET https://auth.example.org/authorize
?response_type=code
&client_id=my-app
&redirect_uri=https://app.example.com/callback
&scope=launch openid fhirUser patient/Patient.r patient/Observation.rs
&state=8f2c1a...
&aud=https://fhir.example.org/r4
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&launch=xyz123
Three parameters cause most failed launches:
audmust be the FHIR base URL exactly as the server knows it, including path and trailing-slash conventions. It tells the authorization server which resource server the token is for.redirect_urimust match a registered redirect URI character for character.- PKCE (
code_challenge, methodS256) is required in SMART v2 for all clients. Theplainmethod isn't allowed.
state protects against CSRF. Generate a random value per request and check it on the callback.
Step 4: scopes
SMART v1 vs v2 syntax
| Meaning | v1 | v2 |
|---|---|---|
| Read one patient's observations | patient/Observation.read | patient/Observation.rs |
| Create and update | patient/Observation.write | patient/Observation.cu |
| Everything on a resource type | patient/Observation.* | patient/Observation.cruds |
| All resource types the user can see | user/*.read | user/*.rs |
| Backend access | system/Patient.read | system/Patient.rs |
v2 letters are create, read, update, delete, search, and must appear in that order. v2 also allows granular scopes with search parameters:
patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
This grants only lab results, not vitals or social history. Servers that support it declare permission-v2 in their capabilities.
Context and identity scopes
| Scope | Gives you |
|---|---|
launch | The EHR launch context (with the launch parameter) |
launch/patient | A patient picked during standalone launch |
launch/encounter | The current encounter |
openid fhirUser | An id_token with a fhirUser claim: the FHIR URL of the logged-in user, e.g. Practitioner/123 |
offline_access | A refresh token that works after the user logs out |
online_access | A refresh token valid only while the user's session is active |
Ask for less, then read what you got
Request only the resources you need. Then always read the scope field in the token response. The server or the user may grant fewer scopes than you asked for, and your app should degrade gracefully, not fail on the first 403.
Step 5: the token response
{
"access_token": "eyJhbGciOiJSUzM4NCIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "launch openid fhirUser patient/Patient.r patient/Observation.rs",
"id_token": "eyJhbGciOiJSUzI1NiJ9...",
"refresh_token": "def50200a1...",
"patient": "123",
"encounter": "enc-456",
"need_patient_banner": true,
"smart_style_url": "https://ehr.example.org/smart-style.json"
}
patientandencounterare the launch context, as plain ids. Use them in your first requests:GET [base]/Patient/123.need_patient_banner: truemeans the EHR isn't showing the patient's name around your app, so you must display it.- The access token may be opaque. SMART doesn't require JWT access tokens, so don't build logic that parses them. Treat the
scopefield as the source of truth. - The id_token is always a JWT. Validate its signature against the
jwks_uri, along withiss,audandexp, before trustingfhirUser.
Backend services (no user)
For server-to-server work such as nightly exports, Bulk Data and analytics, there's no browser and no user. SMART Backend Services uses the OAuth client_credentials grant with a signed JWT instead of a secret:
POST https://auth.example.org/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&scope=system/Patient.rs system/Observation.rs
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzM4NCIsImtpZCI6ImtleS0xIn0...
The client assertion is a short-lived JWT signed with your private key, with iss and sub set to your client id, aud set to the token endpoint, a unique jti, and an exp no more than five minutes ahead. The server verifies it with the public key you registered (or published at a JWKS URL). The spec requires servers to support RS384 and ES384 for these assertions.
Errors that block first launches
| Symptom | Usual cause |
|---|---|
invalid_request at /authorize | aud doesn't match the FHIR base URL, or PKCE missing |
invalid_grant at /token | Code reused or expired, code_verifier doesn't match, or redirect_uri differs from the authorize call |
| Token works, every request is 403 | Granted scope narrower than requested, or patient/ scopes used on another patient's data |
patient missing from token response | Didn't request launch (EHR) or launch/patient (standalone) |
| Backend token rejected | Clock skew on exp, reused jti, wrong aud (must be the token URL), or algorithm not RS384/ES384 |
| Works in sandbox, fails in production | Different iss/base URL, or production registration has different scopes or redirect URIs |
Try it
The SMART Token Inspector decodes access tokens and id_tokens, shows expiry and scope claims, and can verify a signature against a JWKS you paste. The Scope Analyzer explains what a scope string grants per resource and flags mixed v1/v2 syntax. The Configuration Inspector checks a smart-configuration document for missing endpoints, PKCE and capability problems. All three work on text you paste and send nothing to any server.
Standards and references
- SMART App Launch Implementation Guide
- SMART App Launch: Scopes and launch context
- SMART App Launch: App launch flow
- SMART Backend Services
- RFC 7636: PKCE
- ONC certification criterion §170.315(g)(10)
FHIR Toolbox is a free collection of HL7 FHIR tools by Omindra Labs. The tools process your data in your browser; it is not uploaded for normal tool operations.