SMART on FHIR & app launch
OAuth2 dressed for healthcare: how a third-party app launches inside an EHR, asks for scoped access, and reads FHIR with the user's blessing.
The answer in one paragraph
SMART on FHIR is the standard that lets an app you didn't build run against an EHR you
don't control. It is OAuth 2.0 (authorization code + PKCE) with healthcare-specific
additions: launch context so an app opened from a chart knows which patient is on
screen, and scopes shaped like patient/Observation.rs that say exactly what the
app may touch. One app, written once, runs against any SMART-conformant server — the
reason hospital app stores exist.
The launch, step by step
- Discovery — the app reads
.well-known/smart-configurationfrom the FHIR server to find the authorization endpoints and capabilities. - Authorization request — browser redirect with requested scopes
(
launch,openid fhirUser,patient/*.rs); inside an EHR launch, an opaquelaunchtoken ties the request to the open chart. - User/EHR approval — the authorization server authenticates and shows what the app wants.
- Token exchange — auth code (with PKCE verifier) becomes an access token; the
token response carries the context:
patient, maybeencounter,fhirUser. - FHIR calls —
Authorization: Bearer …, constrained server-side to the granted scopes. Refresh tokens (offline_access) keep long-running apps alive.
Scopes: the part to actually memorise
patient/Observation.rs = read+search Observations for the launched patient only;
user/*.cruds = whatever the signed-in clinician may do, across their patients;
system/* = backend services with no human present — paired with SMART Backend
Services (signed-JWT client credentials) for server-to-server jobs like bulk export.
Least privilege is not a nicety here; reviewers and security teams read your scope list
first.
Two flavours of launch
EHR launch: clinician clicks your app inside the chart; context arrives via the launch token — the dominant clinical pattern. Standalone launch: user starts at your app and picks their provider/patient — the dominant patient-app pattern (and what US patient-access regulation rides on).
Where to go next
CDS Hooks & decision support — SMART's sibling: instead of the user opening an app, the EHR calls your service mid-workflow and shows its advice as cards.