SMART on FHIR Integration: App Launch, Scopes, and Auth Explained
"SMART on FHIR" covers more than one flow. The interactive App Launch pattern - where a real person logs in and authorizes access - is a different integration problem than the backend, no-user flow, and conflating the two causes real design mistakes.
EHR launch vs. standalone launch
SMART App Launch supports two launch patterns: EHR launch, where the app is opened from within the EHR's own interface (embedded in a provider's workflow, or a patient's portal), receiving context (like the current patient) from the EHR at launch time; and standalone launch, where the app is opened independently (a patient opening a mobile app on their own) and has to establish patient context itself, typically through the patient logging in and authorizing access via the EHR's authorization server.
These lead to different integration designs: an EHR-launched app can rely on receiving a specific patient/encounter context automatically, while a standalone-launched app needs its own patient selection and authorization flow built out.
Scopes: requesting exactly what you need
SMART on FHIR scopes follow a pattern like `patient/Observation.read` (read access to Observations for the launched patient context) or `user/*.read` (broader read access scoped to what the authenticated user can see) - request the narrowest scopes that satisfy your actual use case, since over-requesting scopes is both a security concern and, in many EHR app review processes, a common source of review pushback and delay.
How this differs from SMART Backend Services
SMART App Launch (both variants) assumes a real user completing an interactive authorization step - a patient or provider actually logging in and consenting. SMART Backend Services (covered in our companion piece) is a separate flow entirely, for system-to-system access with no interactive user, authenticated via a signed JWT and a registered key rather than a login flow. Choosing the right one is the first and most consequential design decision in a SMART on FHIR integration project - get it wrong and much of the early technical work has to be redone under the other model.
App review: budget for it explicitly
Most major EHR vendors require an app review process before granting production access for SMART App Launch apps - typically involving security documentation, a working sandbox demonstration, and iterative feedback from the reviewer. This can take several weeks and should be budgeted as a distinct phase in a project timeline, separate from and often longer than the core technical integration work itself.
FAQ