SMART on FHIR app launch is the standard way healthcare apps start securely, obtain authorization, and receive patient and user context from an EHR or FHIR server. Built on OAuth 2.0 and OpenID Connect, the SMART App Launch framework lets one app work across many EHRs without custom login integrations for each vendor. This guide explains EHR and standalone launch flows, SMART v2 scopes and security requirements, backend services, discovery, and the mistakes that commonly break launches in production. Our HL7 and FHIR integration services implement these flows for clinical and patient-facing apps.
The SMART App Launch framework is an HL7 implementation guide that defines how apps authenticate users, request permission to FHIR data, and receive context such as the current patient or encounter. It standardizes OAuth 2.0 authorization for healthcare, so developers can build once and connect to any compliant FHIR server. If you are new to the underlying data standard, start with what FHIR is, then return to the launch mechanics below.
SMART uses OAuth 2.0 to grant apps scoped access tokens and OpenID Connect to identify the signed-in user. Read our OAuth explained entry for the basics.
Beyond permissions, SMART passes clinical context, such as the selected patient or encounter, so apps open directly to the right record instead of asking users to search again.
Apps request scopes describing which FHIR resources they can access and how. Users or administrators approve them, and the authorization server issues tokens limited to approved scopes.
Because certified EHRs support SMART, a well-built app can launch across multiple vendors with configuration rather than separate custom integrations, dramatically reducing long-term maintenance effort.
The EHR launch is used when a clinician opens your app from inside the EHR. The EHR initiates the launch, passing a launch token and its FHIR server address, and your app exchanges these for an access token tied to the current patient and user. Because users never leave their clinical workflow, EHR launch is the preferred pattern for clinician-facing tools such as calculators, decision support, documentation helpers, and specialty viewers.
The EHR opens your registered launch URL with two parameters: iss, the FHIR server base URL, and launch, an opaque token representing the current session context.
Your app reads the server’s .well-known/smart-configuration document to find authorization and token endpoints, supported scopes, and capabilities before starting authorization for that specific server.
Redirect to the authorization endpoint with client ID, requested scopes including launch, redirect URI, state, and a PKCE code challenge. The EHR typically approves without asking clinicians to log in again.
Your app exchanges the authorization code and PKCE verifier for an access token. The token response includes context such as patient and encounter identifiers and granted scopes.
Use the access token to query FHIR resources for the launched patient. Respect granted scopes, handle token expiry gracefully, and never assume access beyond what was approved.
The standalone launch is used when an app starts outside the EHR, such as a patient app downloaded from an app store or a clinician web app opened directly. The app chooses which FHIR server to connect to and asks the user to sign in and approve access. Patient-facing apps rely heavily on this flow, which certified EHRs must support for patient access to their health information.
Your app needs the FHIR server’s base URL, often chosen by the patient from a list of health systems. Maintain a reliable directory of endpoints for the organizations you support.
The user authenticates with the provider organization’s identity system and reviews requested permissions. Request only necessary scopes, because long permission lists reduce approval rates and patient trust.
For patient apps, the launch/patient scope asks the server to provide the authenticated patient’s identifier. Clinician standalone apps may present a patient picker instead.
Apps needing access after the session ends request offline_access to receive refresh tokens. Store refresh tokens securely and support revocation when users withdraw consent.
Not every integration involves a user. Backend services authorization lets a server application access FHIR data without anyone signing in, for example nightly data syncs, population analytics, quality reporting, or bulk exports. The app authenticates using a signed JWT and the client credentials grant. Because no user approves each request, backend access is tightly controlled through registration, scopes, and administrator approval on the health system side.
Your server signs a JWT assertion with its private key and exchanges it for an access token. Publish public keys through a JWKS endpoint and rotate keys regularly.
Backend apps request system scopes, such as system/Observation.rs, instead of patient or user scopes. Request the narrowest set your integration truly needs to pass security review.
Backend services pair with FHIR Bulk Data to export large patient populations asynchronously. Plan storage, processing, and security for large files containing significant volumes of PHI.
Health systems must register and approve backend clients explicitly. Provide clear documentation of data use, scopes, and security controls to speed their review and approval process.
Most SMART on FHIR failures in production trace back to a handful of avoidable mistakes. Apps hard-code endpoints, request excessive scopes, mishandle tokens, or assume every server behaves identically. These issues may not appear in public sandboxes but surface quickly at real health systems. Experienced SMART on FHIR developers design for variation across servers from the beginning, which saves weeks during customer onboarding.
Never hard-code authorization or token URLs. Always use the iss parameter and SMART discovery document, because endpoints differ across health systems and can change after upgrades.
Broad scopes slow security reviews and lower patient approval rates. Map each feature to the exact resources and operations it needs, then request only those scopes.
Storing tokens in browser local storage or unencrypted mobile storage exposes PHI. Use secure storage, short-lived access tokens, and server-side handling for confidential clients.
FHIR servers differ in supported resources, search parameters, and data completeness. Test against multiple sandboxes and handle missing data gracefully rather than failing entirely.
Expired launches, denied consent, and revoked tokens happen regularly. Show clear messages and recovery steps instead of blank screens that generate support tickets from clinicians.
Our work and story have been picked up by news outlets and databases worldwide.
As featured on
SMART on FHIR app launch is an HL7 standard that defines how healthcare apps authenticate users, request scoped access to FHIR data, and receive context such as the current patient. Based on OAuth 2.0 and OpenID Connect, it lets one app launch securely across many compliant EHRs and FHIR servers.
EHR launch starts inside the EHR, which passes a launch token and server address so the app opens with the current patient and user context. Standalone launch starts outside the EHR, where the app selects a FHIR server and the user signs in and approves access directly.
SMART v2 introduced granular scopes with create, read, update, delete, and search permissions, required PKCE, added asymmetric client authentication, defined token introspection, and organized features into capability sets. Under ONC’s HTI-1 rule, SMART v2 replaced v1 in the certification program beginning January 1, 2026.
Scopes define which FHIR data an app may access and how. Examples include patient-level scopes for the launched patient’s data, user-level scopes for data a clinician can access, system scopes for backend services, and context scopes like launch and openid for identity and session information.
Certified EHRs must support SMART App Launch for their standardized APIs, so well-built apps can work across vendors. However, supported resources, scopes, and approval processes differ, and each health system must register and approve your app. Testing across multiple sandboxes before customer onboarding is essential.
Register your app with target EHR developer programs, implement discovery, launch flows, PKCE, and secure token handling, then build features against FHIR APIs and test across sandboxes. Book a free consultation and our team will scope your SMART on FHIR launch and integration plan.
Tell us what you’re building. Our team will get back to you within one business day with a clear, no-obligation plan.
