SMART on FHIR: What Clinical Teams Need to Know Before Going Live

What SMART on FHIR Actually Does

The problem SMART on FHIR solves is specific: how do you launch a third-party clinical application from within an EHR workflow without requiring the clinician to authenticate separately, without duplicating identity management, and without giving the app unconstrained access to the patient record? Before SMART, the common answer was either a shared-password integration (insecure), a separate login for each external system (workflow-breaking), or an iFrame with session cookies passed through (fragile and ungovernable).

SMART on FHIR's answer is OAuth 2.0 layered over FHIR APIs with a standardised launch protocol. In practical terms for clinical IT teams: the EHR acts as an authorisation server. When a clinician opens a SMART app from within the EHR, the EHR issues a short-lived authorisation code containing the launch context — who the patient is, what encounter is active, who the user is. The SMART app exchanges that code for an access token at the EHR's token endpoint. Every subsequent FHIR API call the app makes carries that token. The FHIR server validates the token before returning any data.

The OAuth 2.0 mechanics matter because they are where most integration problems originate. Knowing that a token has an expiry time, that it encodes specific scopes, and that the authorisation server and resource server (FHIR server) may be separate components — sometimes managed by different vendors — is not developer trivia. It is the architectural context that determines what can go wrong and where to look when it does.

EHR Launch vs Standalone Launch

The SMART App Launch specification defines two launch modes with fundamentally different clinical implications.

EHR launch is the standard for clinical workflow integration. The EHR initiates the sequence by passing a launch parameter and an iss (issuer URL) to the app. The app uses these to retrieve the FHIR server's smart-configuration metadata, begin the authorisation flow, and ultimately receive an access token that already includes the patient and encounter context. The clinician does not have to re-select a patient. The app already knows who it is operating in the context of.

Standalone launch is where the app initiates independently, without an EHR-provided launch token. The user must authenticate and, for patient-facing clinical apps, explicitly select a patient from the FHIR server's patient list. This is appropriate for patient portals, population health dashboards, and administrative tools — but it is not appropriate for point-of-care clinical workflow integration because it reintroduces the re-identification step that SMART was designed to eliminate.

The decision between EHR launch and standalone launch is not purely technical. It determines whether the clinical workflow requires an extra step, and therefore whether clinicians will use the app consistently or route around it.

Scope Design: A Clinical Decision, Not a Technical One

OAuth 2.0 scopes define what clinical data the SMART app is permitted to read or write. The SMART specification uses a structured scope syntax: patient/Observation.read grants read access to Observation resources for the in-context patient; user/MedicationRequest.write grants write access to MedicationRequests for any patient the user can access. The difference between patient/ and user/ prefix, and between .read and .write suffix, has direct clinical data access implications.

Scope design decisions need clinical informatics input, not just developer input. A scope that grants write access to MedicationRequest resources authorises the app to create or modify medication records. A scope that grants read access to all Observations for all patients the user has access to is materially different from one scoped to the in-context patient only. These are clinical governance decisions dressed in technical syntax.

The Production Failure Modes

The part that does not come up in sandbox demos.

EHR Launch Context Not Correctly Passed

The most common production failure in EHR-launched SMART apps is that the patient context is absent or incorrect when the app loads. This happens when the EHR's launch sequence does not correctly populate the patient claim in the access token, or when the app assumes a patient is always present in the launch context but the EHR launches the app from a non-patient context (a ward list, a scheduling screen, an administrative view).

When the patient ID is missing from the launch context, one of three things happens: the app throws an unhandled error and fails to load; the app loads without a patient context and presents empty data, which a clinician may interpret as a real clinical finding; or — in poorly designed apps — the app silently uses the last patient context it cached, which may be a different patient entirely. All three outcomes carry clinical risk.

The app must explicitly handle absent or invalid patient context. The EHR's launch context behaviour must be documented and verified against every screen from which the app can be opened, not just the primary intended entry point.

FHIR Server Scope Support Does Not Match App Requests

The FHIR server's CapabilityStatement (or its SMART-specific .well-known/smart-configuration endpoint) declares what scopes it supports, what FHIR resource types it exposes, and which SMART capabilities — EHR launch, standalone launch, PKCE, token introspection — are implemented. This is the ground truth for what the integration can actually do.

It is common for the FHIR server's declared capabilities to be out of step with what the app was built to expect. The server may not support a scope the app requests. It may support a resource type but not the specific search parameters the app depends on. SMART App Launch 2.0 features like PKCE and granular scopes may not be implemented even if the vendor claims the server is "FHIR R4 compliant." R4 compliance and SMART App Launch 2.0 compliance are independent conformance claims.

Verifying the CapabilityStatement against the app's requirements before development starts is not optional. Discovering the mismatch after build is costly. Discovering it in production is a clinical incident.

Token Refresh Failures in Long Clinical Sessions

OAuth 2.0 access tokens are intentionally short-lived. The SMART specification allows for refresh tokens that extend a session without requiring re-authentication — but the FHIR server must support token refresh, the app must implement the refresh flow correctly, and the EHR's session management must not terminate the underlying authorisation context before the app has finished with it.

A clinician who opens a SMART app at the start of a shift, is interrupted for two hours by clinical activity, and returns to the app to complete a task will encounter a token expiry. If the app handles this gracefully — prompting re-authentication without losing the clinical context — the disruption is manageable. If the app fails silently, presents stale data, or loses an in-progress workflow, the clinical impact can be serious.

Token lifetime and refresh behaviour must be tested with session lengths that reflect actual clinical usage, not developer-session lengths. An eight-hour clinical shift is not a developer edge case. It is the standard operating environment.

Consent and Access Control on Shared Workstations

Many clinical environments operate with shared workstations. A clinician authenticates, opens the SMART app, completes a task, steps away, and a second clinician sits down. If the browser session is still active, the second clinician may be able to access the first clinician's authorised SMART session — including any patient data it has loaded.

This is not a theoretical concern. Session timeout enforcement in the SMART app, alignment with the EHR's session lock behaviour, and clear clinical guidance on shared workstation practice are all necessary. The OAuth 2.0 specification does not solve the physical access control problem. Local governance does.

Audit Trail Requirements Not Met

Clinical systems operating in regulated healthcare environments have legal and clinical safety obligations to maintain an audit trail of who accessed what patient data and when. SMART on FHIR does not automatically produce this audit trail — it provides the authentication and authorisation infrastructure, but audit logging must be explicitly implemented at the FHIR server level and, where write-back operations occur, at the application level.

Common gaps: the audit log records that a token was issued but not which FHIR resources were subsequently accessed; write-back operations are captured in the FHIR server's audit log but not in the EHR's native audit log, creating a split audit trail that is difficult to reconcile; and the audit log is not reviewed as part of go-live readiness, so gaps are not discovered until a clinical incident creates an obligation to produce access records.

The Clinical Safety Considerations

Scope Design and Clinical Intent Alignment

The scopes granted to a SMART app define what clinical data it can read and write. Whether those scopes accurately reflect what the app should be able to do is a clinical governance question, not a technical one. An app that was scoped to read Observations may have been designed to read vital signs observations — but the scope, as granted, covers all Observation resources for the in-context patient, including sensitive observations the clinical team did not intend to expose.

Scope design must be reviewed by clinical informatics before the authorisation flow is built, not after. The question to answer: does every scope the app requests match a specific clinical action that the app has been approved to perform, for a defined user population, with the patient consent model that applies in this clinical environment?

Write-Back Operations and Wrong-Context Risk

SMART apps that write back to the FHIR server — creating a new MedicationRequest, updating a Condition, adding a clinical note — carry a category of risk that read-only apps do not. The most serious variant is a write-back that occurs against the wrong patient because the launch context was incorrect, cached incorrectly, or not validated before the write was committed.

Partial updates are a second failure mode. FHIR's PATCH operation allows partial resource updates, but if the app sends an incomplete or malformed patch — for instance, a MedicationRequest that does not include a required dosage instruction — the FHIR server may accept the resource if its validation rules are permissive, creating a clinically incomplete record.

Write-back operations require explicit patient context validation immediately before the write, not just at launch time. The patient ID in the app's current state must match the patient ID in the active access token.

Patient Matching and National Identifier Verification

When an EHR passes a patient identifier in the launch context — an NHI number in New Zealand, an NHS number in the UK — that identifier is passed as asserted. The SMART app typically treats the identifier as verified and uses it to retrieve FHIR Patient resources. If the EHR has a patient matching error — a duplicate NHI, an incorrectly merged record, or an unverified identifier that has not yet been validated against the national index — the SMART app will operate on incorrect patient data without any indication that a matching problem exists.

Clinical safety obligations require that patient matching quality is understood and documented before a SMART app that uses those identifiers goes live. The SMART app does not fix upstream patient matching problems. It inherits them.

Downtime Handling and Silent Data Staleness

A SMART app that depends on a FHIR server which becomes unavailable will either fail to load, fail to refresh data, or — in the worst case — continue to display cached data from an earlier successful load without indicating to the clinician that the data may be out of date. The last scenario is the most dangerous, because a clinician who sees lab results, medication lists, or vital signs presented without a staleness warning may act on data that no longer reflects the patient's current clinical status.

FHIR server downtime must be treated as a first-class test scenario, not an edge case. The app must display an explicit, prominent indicator when data cannot be confirmed as current. Clinical workflows must have a defined fallback — a paper process, a direct EHR lookup — that clinicians know to use when the SMART app is unavailable.

What Good SMART on FHIR Delivery Looks Like

• FHIR server CapabilityStatement verified before development starts. The app's scope requirements, resource access patterns, and SMART capability dependencies are mapped against what the server actually declares. Mismatches are resolved before build, not during testing.
• Scope design reviewed by clinical informatics. Every scope the app requests is traceable to a specific, clinically approved action. Read vs write, patient-context vs user-context, and sensitive data categories are all explicitly reviewed — not left to the development team to determine.
• Test scenarios that cover EHR launch failure, token expiry, and FHIR server downtime. The test plan is not limited to the happy path. EHR launch without a patient context, token expiry mid-session, FHIR server returning 503, and write-back with an invalid patient context are all tested before go-live. Inferno and similar conformance test suites are used as part of the test strategy.
• Audit logging confirmed before go-live and mapped to clinical safety obligations. The audit trail covers both access events (what patient data was retrieved, by whom, when) and write events (what changes were made to clinical records via the SMART app). The log format is confirmed to be usable for clinical safety investigations and regulatory reporting.
• Rollback plan defined and tested before go-live. If the SMART app fails in production, the clinical workflow it supports does not fail with it. The fallback process — whether that is a direct EHR function, a paper process, or a different application — is documented, communicated to clinical users, and tested under realistic conditions before cutover.

Frequently Asked Questions