Written and maintained by CASRAI Editorial Board
Last updated
SMART on FHIR (Substitutable Medical Applications, Reusable Technologies on Fast Healthcare Interoperability Resources) is an open, standards-based healthcare application platform specification maintained by Health Level Seven International (HL7) that enables third-party clinical decision support tools, patient-facing mobile applications, and clinical research modules to run securely across different Electronic Health Record (EHR) systems without custom vendor-specific interface code. Mandated across U.S. certified EHR technology under the ONC 21st Century Cures Act Final Rule (45 CFR § 170.315(g)(10)), SMART on FHIR combines HL7 FHIR RESTful APIs and HL7 US Core profiles with OAuth 2.0 authorization and OpenID Connect (OIDC) authentication.
What Is SMART on FHIR?
Originally developed in 2010 by the Computational Health Informatics Program (CHIP) at Boston Children’s Hospital and Harvard Medical School (led by Kenneth Mandl and Isaac Kohane) and later adapted to the HL7 FHIR specification, SMART on FHIR solves a foundational problem in clinical informatics: allowing a ‘substitutable’ clinical or research application to be written once and launched inside—or connected to—any conformant EHR (including Epic and Oracle Health [Cerner], MEDITECH, athenahealth, and NextGen) or interoperable research information system.
The SMART on FHIR architecture rests on four standardized technical layers:
- Clinical Data Model and API Layer (HL7 FHIR & US Core): Clinical data is queried and written as standardized JSON or XML resources (such as
Patient,Observation,Condition,MedicationRequest, andDocumentReference) constrained by national profiles such as the HL7 FHIR US Core Implementation Guide. - Authorization Layer (OAuth 2.0, RFC 6749 & PKCE, RFC 7636): Delegated access control ensures that the SMART application never sees or stores the clinician’s or patient’s EHR credentials. Instead, the EHR’s authorization server issues a time-limited, scope-restricted OAuth 2.0
access_token(and optionalrefresh_token). In SMART App Launch v2.0+, all public and confidential clients using the authorization code flow must implement Proof Key for Code Exchange (PKCE) using theS256(SHA-256) challenge method. - Authentication Layer (OpenID Connect Core 1.0): When an application requests the
openidandfhirUserscopes, the authorization server returns a cryptographically signed JSON Web Token (id_token) identifying the authenticated user and providing a direct FHIR resource URL (such asPractitioner/123orPatient/456). - UX and Context Integration Layer (SMART App Launch & CDS Hooks): Defines how the EHR passes the active clinical session context—specifically which patient chart and which clinical encounter are currently open on screen—to the launched application.
SMART on FHIR App Launch Flows: EHR Launch vs. Standalone Launch
The HL7 SMART App Launch Implementation Guide defines two primary user-facing launch sequences, plus a backend services profile for system-to-system data pipelines:
| Launch Workflow | How the SMART on FHIR Application Starts | Context Parameters & Handshake | Typical Healthcare & Research Use Cases |
|---|---|---|---|
| EHR Launch (In-Context Clinician or Portal Launch) | A clinician or user clicks an embedded app tab or button inside an active EHR chart session (often rendered in an HTML5 iframe or new browser tab). |
EHR calls the app’s launch URL with two GET parameters: iss (the FHIR server base URL) and launch (an opaque one-time context handle). The app queries {iss}/.well-known/smart-configuration, then redirects to the authorization endpoint passing launch={launch} and scope launch. |
Point-of-care clinical calculators (ASCVD, bilirubin charts), genomic variant viewers, ambient AI scribes, and clinical trial eligibility screening apps inside the EHR chart. |
| Standalone Launch (Patient or External App Launch) | A patient or clinician opens a mobile iOS/Android app or external web application directly, outside the EHR user interface. | The user selects their healthcare institution from an endpoint directory. The app fetches /.well-known/smart-configuration and initiates OAuth 2.0 authorization requesting explicit context scopes (such as launch/patient or launch/encounter). |
Patient-facing personal health record (PHR) mobile apps, Apple Health records integration, decentralized clinical trial (DCT) ePRO/eConsent mobile apps. |
| SMART Backend Services (System-to-System) | An automated server daemon or research ETL pipeline connects to the EHR FHIR server with no human user in the loop. | Uses the OAuth 2.0 client_credentials grant with asymmetric public/private key JWT assertions (RFC 7523) and system/* scopes; often paired with the FHIR Bulk Data Access ($export) API. |
Nightly population health cohorts, multi-site registry synchronization, and automated EHR-to-EDC clinical trial data ingestion. |
Step-by-Step EHR Launch Sequence
When a clinician opens a SMART on FHIR app inside an EHR patient chart, four HTTP steps execute in under a second:
- 1. EHR Initiates Launch Request: The EHR navigates to the registered
launch_uriof the SMART app, appending?iss=https://fhir.examplehospital.org/r4&launch=xyz987. - 2. Endpoint Discovery: The SMART app validates the
issURL against its allowlist of trusted FHIR servers and sends an HTTPGETrequest tohttps://fhir.examplehospital.org/r4/.well-known/smart-configurationto retrieve the server’sauthorization_endpointandtoken_endpoint. - 3. OAuth 2.0 Authorization Redirect: The app generates a cryptographic
stateparameter and PKCEcode_verifier/code_challenge(code_challenge_method=S256) and redirects the browser to the EHR’sauthorization_endpointwithresponse_type=code,client_id,redirect_uri,launch=xyz987,scope=launch openid fhirUser patient/Patient.rs patient/Observation.rs, andaud={iss}. - 4. Token Exchange and FHIR Resource Queries: After the EHR validates the active session, it redirects back to the app’s
redirect_uriwith an authorizationcode. The app posts thecodeandcode_verifierto thetoken_endpointand receives a JSON token response containingaccess_token,id_token,patient(e.g.,'patient': 'example-pt-101'), andencounter. The app then queriesGET {iss}/Observation?patient=example-pt-101&category=vital-signsusing the HTTP headerAuthorization: Bearer {access_token}.
SMART on FHIR Scopes: v1 vs. v2 Granular Permissions
SMART on FHIR enforces the principle of least privilege through structured OAuth 2.0 scopes that specify both the access category (patient/ for records restricted to the single in-context patient, user/ for records the authenticated clinician or user is permitted to access across the EHR, or system/ for backend services) and the allowed operations:
- SMART v1 Scope Syntax (
.read,.write,.*): Used in initial ONC Cures Act deployments—for example,patient/Immunization.read(read and search immunizations for the active patient) oruser/Observation.write. - SMART v2 Scope Syntax (
.c,.r,.u,.d,.s): Introduced in HL7 SMART App Launch v2.0.0 to provide fine-grained separation between reading by ID and searching, using any combination ofc(create),r(read),u(update),d(delete), ands(search) in that order—for example,patient/Observation.rs(read and search observations) oruser/QuestionnaireResponse.cruds. SMART v2 also supports sub-resource scope filtering by FHIR search parameters, such aspatient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory(restricting access strictly to laboratory observations rather than mental health or social history observations). - Context and Lifecycle Scopes:
launch(EHR launch context),launch/patient(standalone patient selection),launch/encounter(standalone encounter selection),openid+fhirUser(OIDC user identity), andonline_accessoroffline_access(requesting a refresh token).
ONC 45 CFR § 170.315(g)(10) Certification and Clinical Research Applications
In the United States, the widespread availability of SMART on FHIR across hospital and ambulatory EHRs is driven by the Office of the National Coordinator for Health Information Technology (ONC) certification criterion 45 CFR § 170.315(g)(10) (Standardized API for patient and population services):
- Mandatory Support Across Certified EHRs: Every EHR certified under the ONC Health IT Certification Program (listed on the Certified Health IT Product List, CHPL) must expose a conformant HL7 FHIR R4 API supporting HL7 US Core profiles and the SMART App Launch Framework for both patient standalone access and clinician EHR launch.
- Patient Access Without Special Effort: Under the Cures Act Information Blocking rules (45 CFR Part 171) and § 170.315(g)(10), patients have the right to authorize third-party SMART on FHIR applications of their choice to retrieve their USCDI health data using their patient portal credentials.
- Clinical Research and EHR-to-EDC Integration: Academic medical centers and trial sponsors use SMART on FHIR applications for three core research workflows: (1) Point-of-Care Trial Recruitment, where a CDS Hooks card triggers a SMART on FHIR screening app when a patient’s labs and ICD-10/SNOMED problem list match trial inclusion criteria; (2) EHR-to-EDC eSource Pre-Population, pulling verified US Core vital signs, concomitant medications, and laboratory panels directly into electronic case report forms (eCRFs) via the HL7 Vulcan RWD / EHR-to-EDC profiles; and (3) Participant-Mediated Real-World Data (RWD) Sharing, where trial participants use a standalone SMART on FHIR mobile app to connect their health system portal and contribute longitudinal EHR records to a registry.
Frequently Asked Questions
What is SMART on FHIR?
SMART on FHIR (Substitutable Medical Applications, Reusable Technologies on Fast Healthcare Interoperability Resources) is an open HL7 standard that combines FHIR clinical data APIs with OAuth 2.0 authorization, OpenID Connect authentication, and standardized EHR launch context so third-party clinical and patient apps can run securely across different EHR systems without custom integration code.
What is the difference between a SMART on FHIR EHR launch and a standalone launch?
In an EHR launch, a user opens the SMART on FHIR app directly from inside an active EHR session, and the EHR passes the FHIR server URL (iss) and an opaque launch context token (launch) so the app automatically loads the active patient and encounter. In a standalone launch, the user opens the app independently (such as on a smartphone or external website), selects their healthcare provider’s FHIR endpoint, and logs in through the EHR’s OAuth 2.0 authorization screen using scopes like launch/patient.
How does ONC 45 CFR § 170.315(g)(10) regulate SMART on FHIR applications?
Under ONC certification criterion 45 CFR § 170.315(g)(10), all certified EHR systems in the United States must provide standardized HL7 FHIR R4 APIs implementing the HL7 SMART App Launch Framework and US Core Implementation Guide, enabling both clinician-facing EHR-launched apps and patient-authorized standalone apps to access United States Core Data for Interoperability (USCDI) elements.
