SMART on FHIR Explained: Everything Developers Need to Know

If you are building healthcare software that needs to work inside or alongside an electronic health record (EHR), you will run into SMART on FHIR fast.

SMART on FHIR is the closest thing the industry has to a universal plug for healthcare apps, and understanding it is the difference between an integration that takes weeks and one that takes months. We have used it across multiple client engagements, and this is the explanation we wish existed when we started.

First, the name

SMART on FHIR is exactly what it sounds like: SMART built on top of FHIR.

FHIR (Fast Healthcare Interoperability Resources, pronounced "fire") is a modern standard from HL7 for exchanging healthcare data. It defines data as "resources" (a Patient, an Observation, a Medication, and so on), each with a consistent structure, exchanged over ordinary RESTful web APIs using JSON.

If you have ever worked with a modern web API, FHIR will feel familiar.

SMART (Substitutable Medical Applications, Reusable Technologies) is the layer that handles the parts FHIR alone does not: how an app launches, how it authenticates, and how it gets permission to access data. SMART standardizes this using OAuth 2.0 and OpenID Connect, the same authorization standards used across the modern web.

Put them together and you get a standard way to build an app once and have it integrate with any compliant EHR, providing secure, scoped access to patient data.

How a SMART on FHIR app actually launches

There are two launch patterns, and knowing the difference matters:

1. EHR launch. A clinician is inside the EHR, looking at a patient, and clicks your app. The EHR hands your app context (which patient, which encounter) and kicks off the authorization flow. Your app already knows who it is dealing with.
2. Standalone launch. The user opens your app directly, outside the EHR. Your app initiates the authorization flow itself, and the user authenticates.

In both cases, the flow ends with your app holding an OAuth access token scoped to exactly the data the user approved, which it then uses to make FHIR API calls.

Scopes: the part people get wrong

SMART uses OAuth scopes to control exactly what your app can read or write.

A scope like patient/Observation.read means "read access to observations for the single patient in context," while user/Observation.read means "read access to observations for everything the logged-in user can see."

Getting scopes right is both a functionality issue and a compliance issue. Request the narrowest scope that does the job. Over-requesting access is a red flag during security review and a liability if you're ever breached.

Where SMART on FHIR shines, and where it does not

SMART on FHIR is excellent for read-heavy, patient-context apps, e.g. pulling a problem list, displaying labs, showing medications, or running a risk calculator on existing data. It is genuinely write-once-run-anywhere for those use cases.

Where it falls short: it's less complete for heavy write operations and for workflows that fall outside the resources the target EHR has implemented.

FHIR is a standard, but EHR vendors implement different versions and different subsets of it. The honest reality is that "supports FHIR" still requires you to test against each specific EHR you intend to support. Do not assume parity.

The bottom line

SMART on FHIR is the foundation of modern healthcare interoperability, and for most app developers it is the right starting point.

Learn the FHIR resource model, understand the SMART launch and authorization flows, and be disciplined about scopes. Then test against the real EHRs you care about, because the gap between the standard and any given vendor's implementation is where the surprises live.