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.

What Is the SMART App Launch Framework?

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.

Built on OAuth 2.0 and OpenID Connect

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.

Launch Context

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.

Scopes Define Data Access

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.

One App, Many EHRs

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.

SMART on FHIR EHR Launch Flow

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.

Step 1: EHR Calls Your Launch URL

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.

Step 2: Discover Authorization Endpoints

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.

Step 3: Request Authorization

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.

Step 4: Exchange the Code for Tokens

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.

Step 5: Call FHIR APIs With Context

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.

SMART on FHIR Standalone Launch Flow

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.

Selecting the FHIR Server

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.

User Login and Consent

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.

Patient Selection Context

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.

Offline Access and Refresh Tokens

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.

SMART v2: What Changed and Why It Matters

SMART App Launch 2.0 introduced stronger security and more precise permissions compared with version 1. Under ONC’s HTI-1 Final Rule, the SMART v2 guide replaced v1 as the version used in the Health IT Certification Program beginning January 1, 2026. Apps built against older assumptions may still work in some environments, but new development should follow v2 patterns to align with certified EHRs and avoid future breakage.

Granular Scope Syntax

SMART v2 replaces read and write with finer permissions such as create, read, update, delete, and search, and allows scopes narrowed by parameters like category for more precise access.

PKCE Required

Proof Key for Code Exchange protects authorization codes from interception. SMART v2 requires PKCE using the S256 method, so implement it in every authorization code flow from the start.

Asymmetric Client Authentication

Confidential clients can authenticate with signed JSON Web Tokens instead of shared secrets. Asymmetric keys reduce the risk of leaked credentials compromising your application’s access across environments.

Token Introspection and Capability Sets

SMART v2 defines token introspection so resource servers can validate tokens, and organizes features into capability sets that clarify exactly what a server supports for patient and clinician apps.

Plan for SMART 2.2

Federal policy has proposed adopting later SMART versions in future certification cycles. Track HL7 and ONC updates and design your authorization layer so version upgrades remain configuration changes.

SMART Backend Services for System-to-System Access

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.

Client Credentials With Signed JWTs

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.

System-Level Scopes

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.

Bulk Data Exports

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.

Administrator Approval

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.

Common SMART on FHIR Implementation Mistakes

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.

Hard-Coding Endpoints

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.

Requesting Excessive Scopes

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.

Insecure Token Storage

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.

Ignoring Server Variation

FHIR servers differ in supported resources, search parameters, and data completeness. Test against multiple sandboxes and handle missing data gracefully rather than failing entirely.

Skipping Launch Error Handling

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.

Frequently Asked Questions

What is SMART on FHIR app launch?

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.

What is the difference between EHR launch and standalone launch?

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.

What changed in SMART App Launch v2?

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.

What are SMART on FHIR scopes?

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.

Do SMART on FHIR apps work with every EHR?

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.

How do I build a SMART on FHIR app?

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.