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 the launch scope.

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:

  • aud must 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_uri must match a registered redirect URI character for character.
  • PKCE (code_challenge, method S256) is required in SMART v2 for all clients. The plain method 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

Meaningv1v2
Read one patient's observationspatient/Observation.readpatient/Observation.rs
Create and updatepatient/Observation.writepatient/Observation.cu
Everything on a resource typepatient/Observation.*patient/Observation.cruds
All resource types the user can seeuser/*.readuser/*.rs
Backend accesssystem/Patient.readsystem/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

ScopeGives you
launchThe EHR launch context (with the launch parameter)
launch/patientA patient picked during standalone launch
launch/encounterThe current encounter
openid fhirUserAn id_token with a fhirUser claim: the FHIR URL of the logged-in user, e.g. Practitioner/123
offline_accessA refresh token that works after the user logs out
online_accessA 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"
}
  • patient and encounter are the launch context, as plain ids. Use them in your first requests: GET [base]/Patient/123.
  • need_patient_banner: true means 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 scope field as the source of truth.
  • The id_token is always a JWT. Validate its signature against the jwks_uri, along with iss, aud and exp, before trusting fhirUser.

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

SymptomUsual cause
invalid_request at /authorizeaud doesn't match the FHIR base URL, or PKCE missing
invalid_grant at /tokenCode reused or expired, code_verifier doesn't match, or redirect_uri differs from the authorize call
Token works, every request is 403Granted scope narrower than requested, or patient/ scopes used on another patient's data
patient missing from token responseDidn't request launch (EHR) or launch/patient (standalone)
Backend token rejectedClock skew on exp, reused jti, wrong aud (must be the token URL), or algorithm not RS384/ES384
Works in sandbox, fails in productionDifferent 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

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.