SMART on FHIR: Launch, Scopes and Security

SMART on FHIR combines a standard app launch, authorization, and FHIR clinical data access so applications can connect to electronic health records. Product teams need to get launch context, least-privilege scopes, security checks, and per-EHR compatibility right, since resources, search behavior, and approval requirements can differ across systems.

Why a Certified EHR Must Speak SMART on FHIR

SMART on FHIR is an open app-launch and authorization profile that lets one healthcare application run against different electronic health records. It combines HL7 FHIR resources for clinical data, OAuth 2.0 for permission, and a standard way to pass the selected patient and signed-in user into the app. Say a clinician opens a chart and launches a lab review tool from inside the record. The tool shouldn't ask the clinician to find the patient again, and it shouldn't invent its own login. SMART defines how that handoff happens.

The regulatory reason comes first for most U.S. products. Under the ONC Cures Act Final Rule, certified health IT must offer standardized APIs so third-party apps can reach structured clinical data under defined authorization and patient-context rules, a requirement described in the HealthIT.gov overview of the Cures Act API standards. That makes SMART on FHIR a platform contract your team designs against, whether you sell to hospitals, build patient-facing tools, or add an embedded module to an existing product.

Where the standard came from

The history is short. The SMART Health IT project began in 2010, when Harvard Medical School and Boston Children's Hospital received a four-year, $15 million award from the U.S. Office of the National Coordinator for Health Information Technology, as recorded in the peer-reviewed history of the SMART project. The goal was to let developers build a medical application once and run it across different record systems. In 2013, the project built an open-source FHIR API server and adopted HL7's emerging FHIR standard.

In January 2014, Cerner, Intermountain Healthcare, Hewlett-Packard for the U.S. Veterans Administration, and Harris Corporation demonstrated prototype implementations. FHIR reached the Draft Standard for Trial Use milestone in the same month. That pairing, FHIR resources plus OAuth-based authorization plus web launch, is still the architecture teams implement today.

For buyers, the practical questions are what the server publishes, which scopes it honors, and how your team will handle gaps. Those decisions sit inside larger work such as custom healthcare software development, where security review should start early. Teams planning that review can use continuous threat modeling for healthtech teams as a prompt to map threats against each launch path before code hardens.

FHIR Data, OAuth and Launch Context

Think of SMART on FHIR as three contracts that travel together. FHIR resources are the clinical vocabulary, typically Patient, Observation, MedicationRequest, and Encounter, narrowed by the US Core profiles an EHR exposes. OAuth 2.0 is the permission system. An authorization server issues an access token limited to granted scopes, and the app sends that token as a bearer token when it calls the FHIR base URL. Launch context tells the app which patient, encounter, or user is already selected, so the clinician doesn't repeat a search.

One analogy covers it, and then you can drop it. FHIR is the chart's language, OAuth is the badge, and launch context is the open exam room. A badge doesn't tell you how to read the chart. The chart's language doesn't prove you're allowed in the room. You need all three working together before a screen can safely show clinical data.

The roles behind the contracts

Name the roles before you write code, because each role decides where a control belongs. The EHR's FHIR server acts as the resource server and is often paired with the authorization server that decides whether to issue a token. Your app is the OAuth client that requests tokens. The clinician's browser carries the redirect between them.

Your backend, or your browser code for a public client, has to handle each role's responses correctly. A token error points to an authorization failure rather than a FHIR parsing failure. A valid token permits access, while the returned Observation still needs to be checked for the fields your logic requires. Separating those failures early saves painful debugging during site testing.

Discovery ties the roles together. The app reads the server document at .well-known/smart-configuration to find the authorization and token endpoints and to see which launch and challenge methods the server supports. Don't hard-code those endpoints from a sandbox and assume production matches.

What each contract gives the app

Use this table as a design checklist. Each row should have an owner on your team and a test that proves it works against a real target server.

What each SMART on FHIR contract gives the app

Add OpenID Connect only when the product needs a signed-in user identity. The scopes openid and fhirUser, when granted, allow the app to receive an ID token. If your app only needs patient data for a chart already open, requesting identity scopes adds consent surface without improving the feature.

The mapping work sits between these contracts and your own product model. Your internal objects rarely match FHIR resources field for field, so someone must decide how codes, units, statuses, and missing values translate. That's the core engineering behind FHIR integration services and the FHIR and HL7 integration services guide. Vague assumptions turn into site-specific defects if nobody writes the mapping down.

A screen is ready to build when the team can name the FHIR resource, scope, and launch context it depends on.

EHR Launch Versus Standalone Launch

Choose a launch style before you write the authorize URL. Swapping flows later changes your scope request, your consent screen, and your handling of patient selection. Both flows end with an access token, but each establishes patient context differently.

In an EHR launch, the record system opens the app and places an opaque launch handle on the launch URL. The app returns that handle on the authorization request so the server can attach session context, including the selected patient, as described in the HL7 SMART App Launch specification. The launch scope is what permits that embedded context. Treat the handle as opaque. Don't parse it, store it as a clinical identifier, or reuse it after the launch completes.

In a standalone launch, the user opens the app outside the EHR, from a phone, a portal link, or a bookmark. There's no session handle because there's no EHR session. The launch/patient scope asks the authorization server to have the user pick a patient during consent. If you request the wrong context scope, the server may reject the request or return a token without the patient context your first screen expects.

The shared sequence in order

Both flows then follow the same redirect and token exchange. Write these steps into your implementation ticket, not just your architecture diagram.

1. Discover endpoints: Fetch .well-known/smart-configuration and read the authorization and token endpoints.

2. Create PKCE values: Generate a verifier and derive its S256 challenge.

3. Redirect to authorize: Send the client ID, redirect URI, requested scopes, state, code challenge, and, for an EHR launch only, the launch handle.

4. Validate the return: Reject the response if state does not match what you sent.

5. Exchange the code: Post the authorization code and the verifier to the token endpoint.

6. Plan for expiry: Read expires_in from the token response and plan a new authorization when the token lapses.

7. Call FHIR safely: Call the FHIR base URL with the bearer token, never place it in a URL or long-lived browser storage, and confirm the token audience matches the FHIR server you're calling.

Step 6 catches teams out. A token that works during a short demo can expire mid-shift, and an app that responds with a blank screen will lose clinicians quickly. Decide what the user sees when reauthorization is needed, and test that path on purpose by using short-lived tokens in your sandbox.

Step 7 matters just as much. A token issued for one FHIR server shouldn't be replayed against another, even if both sit behind similar URLs. Checking audience expectation is a small control that prevents a confusing class of wrong-environment bugs.

EHR launch and standalone launch side by side

If your product supports both styles, build them as two explicit entry points with separate tests. Don’t detect the flow by guessing from missing parameters and then improvise. Explicit entry points make consent behavior predictable, and predictable consent behavior is what hospital reviewers want to see.

Scope Strings That Enforce Least Privilege

A SMART scope encodes who the access is for, which FHIR resource is involved, and which operations are allowed. SMART App Launch 2.0 writes that structure as patient, user, or system, then a FHIR resource or wildcard, then a dot and the letters c, r, u, d, and s for create, read, update, delete, and search, according to the US Core scopes documentation. The current published version on hl7.org is SMART App Launch 2.2 (STU 2.2). An optional search parameter can narrow the set further.

Read a scope from left to right, and it tells a story. The subject says whose data boundary applies. The resource says which clinical concept is exposed. The letters say what the app may do to it. If any part is broader than the screen needs, the request is broader than it should be.

Four strings worth decoding

• patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory: Read and search laboratory observations for the current patient only. This fits a lab results screen that has no business reading medications or notes.

• patient/*.rs: Read and search any resource for the current patient. That’s broader than most single-purpose screens need, even though it stays inside one patient’s chart.

• user/*.cruds: Create, read, update, delete, and search whatever the authorizing user can already access. That’s a clinician workspace permission, not a single-chart permission, and reviewers will read it that way.

• system-level read scope: Fits a backend client with no interactive user, such as a scheduled quality job. Treat it as an organizational grant because no patient or clinician selection narrows it at launch.

The difference between the first and second examples is the difference between a defensible request and a difficult approval meeting. A lab viewer requesting every resource for the patient invites questions it can’t answer well. Why does it need conditions, procedures, and documents to draw a lab trend? If the honest answer is convenience during development, fix the scope before production.

The third example deserves extra caution. user/*.cruds includes write and delete across the user’s reach. Some clinician tools need write access, for example, to file a note or update a care plan. Name the resource and keep the letters tight. A tool that creates one resource type shouldn’t request delete on everything.

Context scopes are not data scopes

Don’t confuse launch and launch/patient with clinical access. They grant context, the right to learn which patient or session the app is bound to. They don’t grant permission to read an Observation or a MedicationRequest. Your request usually needs a context scope plus one or more resource scopes, and each part should be justified separately.

A server also only honors scopes it publishes. US Core documents resource-level forms such as patient/Patient.rs, user/Patient.rs and system/Patient.rs, with support depending on the server’s published SMART capability declarations. Check that publication for each target EHR instead of copying a scope list from a tutorial or a previous customer.

Each screen should name the resources it touches and the minimum operation letters it requires, with wildcard scopes kept in the sandbox.

Build a scope-to-screen map during design. It takes an afternoon, and it becomes evidence later when a privacy reviewer asks why your app requests what it requests. Teams that skip the map usually reconstruct it under pressure, after the first rejection, when changing scopes also means retesting consent screens.

PKCE and the Other Launch Security Checks

Start with the current rule. SMART applications must support Proof Key for Code Exchange, or PKCE. Authorization servers must support the S256 challenge method, and they must not support the weaker plain method, under the SMART App Launch 2.1 conformance guidance. This is not an optional hardening item to schedule after launch.

The threat is concrete. A browser or mobile app is a public client, which means it can’t hide a client secret from anyone who inspects the code or intercepts traffic on the device. Say an attacker steals the authorization code during the redirect. Without PKCE, that code may be enough to redeem a token. With PKCE, the attacker still needs the high-entropy verifier that produced the S256 challenge sent at the start, and the verifier never travels with the authorize request.

The fixed implementation order

The sequence has no flexibility. Generate a cryptographically random verifier for each authorization attempt. Derive its S256 challenge. Send the challenge on the authorize request. Send the verifier only on the token request, when you exchange the returned code. Reusing a verifier across launches, or deriving it from something predictable like a timestamp, defeats the control.

Read the supported challenge methods from SMART metadata before you assume S256 is available. Discovery exists so your app can confirm server behavior instead of guessing. If a target server advertises only plain, that’s a finding to raise with the site, not a reason to downgrade your client.

Checks a review should fail the build for

• Mismatched state: The returned state value doesn’t match what the app sent.

• Missing TLS: Any step in the redirect or token exchange runs over an unprotected connection.

• Unexpected issuer: The token or discovery document comes from an issuer the app didn’t expect for that EHR.

• Unregistered redirect URI: The app uses a redirect URI that wasn’t registered with the authorization server.

• Token in a query string: An access token appears in a URL, where logs and browser history can capture it.

• Token in long-lived browser storage: A token sits in storage that survives the session and widens the theft window.

Cover these controls with automated SMART conformance tests and a security review before a hospital pilot. A FHIR resource that parses correctly can still be reached through a broken token exchange, and the hospital’s security team will test the exchange, not just your JSON handling. Identity questions usually surface in the same review, so it helps to align your answers with a clear approach to healthcare identity management before reviewers ask who owns each decision.

Use Cases That Still Need a Compatibility Matrix

Four common patterns show why one integration design doesn’t fit every SMART on FHIR product. They differ in launch style, data needs, and failure tolerance, even when they share the same authorization shape.

A chart-embedded decision aid uses EHR launch and a narrow patient resource set, such as recent labs or active medications. Its main risk is latency and clutter inside a busy workflow. A patient-facing app started from a portal or phone, uses standalone launch with launch/patient, and its main risk is confusing consent. A medication-education tool deployed across several pharmacy and clinic sites faces a different problem. The same build must tolerate different EHR behaviors at each site, so rollout discipline matters as much as the first successful launch. A quality or population job uses system scopes with no interactive chart, and its risk sits in governance because no clinician narrows the data at runtime.

Why plug-and-play breaks down

An EHR can advertise SMART on FHIR and still expose a different resource subset, a different US Core profile, extra extensions, uneven search support, or a workflow that never writes the field your app expects. Recent implementation research presented through AMIA symposium proceedings identifies technical incompatibility, limited organizational capacity, and policy uncertainty as persistent barriers even where federal policy promotes FHIR adoption. Standards adoption can rise while real portability stays limited.

A passing conformance test proves your app speaks the protocol. It doesn’t prove the next hospital’s data will answer your clinical question.

Keep one compatibility matrix per target EHR. Record required resources, fields that come back empty, extensions you must normalize, the API version, search parameters that work, and the empty-state behavior when data is missing. Update it from test results against that site’s sandbox and, later, its production-like environment. A matrix built from vendor documentation alone will flatter you.

Version your own API contract too. If a partial EHR can’t supply a field, your app should degrade in a designed way, for example by hiding a risk score and showing the underlying values with a note. It shouldn’t omit a clinical safety check and present the result as complete. That distinction belongs in product requirements, not in a support ticket after go-live.

Products sold in more than one country inherit different consent and privacy rules on top of the same OAuth shape. The matrix should capture those differences as first-class rows, alongside resources and scopes. At this point, EHR integration services and a broader healthcare data interoperability strategy move beyond planning slogans and become testable work your engineers and reviewers can share.

Choose a Launch Model and an Approval Path

Write down three decisions before sprint planning. First, EHR launch, standalone launch, or both, because the context, scope, and consent screen change. Second, the minimum scope set per role, with wildcards removed for production. Third, who at the hospital must approve the app, because a working token exchange doesn’t replace their sign-off.

That approval group often includes security, privacy, clinical informatics, procurement, compliance, and a frontline clinical champion. Each group asks a different question. Security asks how tokens are protected. Privacy asks why each scope is necessary. Clinical informatics asks whether the app saves time or adds clicks. Procurement asks what happens when the contract ends. If you prepare one generic interoperability slide for all of them, you’ll answer none of them well.

Build a short evidence pack

Bring a document reviewers can check. Include your data minimization argument, the scope-to-role map, audit events you’ll produce, clinical safety assumptions, failure modes when a resource is missing, how patient consent behaves, and one measurable workflow benefit stated in plain terms. Keep it short enough that a busy reviewer will read it.

An app that adds clicks or ignores how clinicians already think can be rejected even when SMART conformance passes. Observe the workflow you’re entering, name a local champion, and be ready to show what the clinician stops doing because your app exists.

Take one concrete next step. Pull .well-known/smart-configuration from one target EHR and fill the first rows of your compatibility matrix before promising that the same build will run everywhere. A healthtech software development partner can help turn that matrix into build work through custom healthcare software development and healthcare integrations. We can build a healthtech product from scratch or plug into an ongoing product roadmap, and we’ve built a HIPAA-compliant remote patient monitoring platform as a healthcare IoT application.

Frequently Asked Questions

What is SMART on FHIR in one sentence?

It’s the HL7 profile that launches an app with FHIR data, OAuth 2.0 authorization, and patient or user context, so the same app can target more than one EHR. It standardizes the handoff between the record system and your application.

Is SMART on FHIR the same as FHIR?

No. FHIR is the data and API standard that defines resources such as Patient and Observation. SMART on FHIR is the launch and authorization layer on top of it.

What does patient/Observation.rs mean?

It allows reading and searching of Observation resources for the current patient only. A category parameter can narrow it further, for example, to laboratory results when that’s all the app needs.

Why did our app work in one EHR and fail in another?

Conformance doesn’t guarantee the same resources, profiles, search behavior, or clinical workflow. Test each target EHR against a compatibility matrix and design a clear empty state when a field is absent.

Who approves a SMART app at a hospital?

Expect security, privacy, clinical informatics, procurement, and a clinical owner to sign off, not only the integration engineer. Bring an evidence pack that answers each group’s questions directly.

If you’re planning a SMART on FHIR integration and want the launch model, scope map, and compatibility matrix settled before your first hospital review, talk to us about the engineering and approval work behind it. Visit Bridge Global to discuss your product, your target EHRs, and the safest path from sandbox launch to approved deployment.