Epic SMART on FHIR integration is the work of making a third-party app open inside a health system's Epic workspace, or connect to it from outside, and exchange FHIR R4 data under an OAuth 2.0 token. The app is registered once with Epic, then switched on separately by every Epic organization that wants to use it.
This article covers which launch type fits, how an Epic launch turns into a token, how per-organization endpoints and activation work, what an Epic app can read and write, how event data fits in, and a checklist for the first production site.
What is Epic SMART on FHIR integration?
Launching an app inside Epic?
Agnotic builds SMART on FHIR apps for Epic organizations: launch handling, tokens, FHIR R4 traffic and per-site configuration.
Epic SMART on FHIR integration connects an outside application to a health system's Epic through the HL7 SMART App Launch framework and the FHIR R4 APIs that Epic documents on Epic on FHIR. The app receives a scoped token, often with the open patient's context, and reads or writes only the resources that the Epic organization has enabled for it.
SMART is an HL7 standard, so the launch sequence is the same one used with other certified EHRs. What is specific to Epic is the registration on Epic on FHIR, the per-organization endpoints, the set of Epic APIs beyond the certified minimum, and each health system's own activation and review.
Which launch type fits your Epic app?
Pick the launch type from who starts the work: a clinician inside Epic, a user outside it, or a scheduled system job. Each one uses a different flow and asks for different scopes.
- EHR launch: The clinician opens the app from the Epic workspace, and the app receives patient and often encounter context. This suits decision support, documentation helpers and specialty views of the chart.
- Standalone launch: The user starts at the app, signs in through the health system's authorization server and picks or is matched to a patient. This suits patient-facing apps and clinician tools used outside the chart.
- Backend services: A server authenticates with a signed JSON Web Token and no user is present. This suits population refreshes, Bulk Data exports and overnight reconciliation jobs.
One product can need more than one launch type. A care management tool might use an EHR launch for the clinician view and a backend services client for the nightly cohort export, registered as separate clients with separate scopes.
How does an Epic launch become a token?
An EHR launch from Epic follows the SMART App Launch sequence: Epic calls the app's launch URL, the app discovers the authorization server, requests a code, and exchanges it for a token with context. Getting each step exact is what separates a working sandbox demo from a launch that fails at the first site.
- 1. Launch request: Epic opens the registered launch URL with an iss parameter, which is that organization's FHIR base URL, and a launch parameter that ties the session to the open chart.
- 2. Discovery: The app reads the SMART configuration published under the iss URL to find the authorize and token endpoints. Never hard-code them.
- 3. Authorize: The app redirects to the authorize endpoint with its client ID, the launch value, the requested scopes, a state value, the aud parameter set to the iss URL, and a PKCE code challenge.
- 4. Token: The app exchanges the returned code for an access token. The response carries the granted scopes and launch context such as the patient ID.
- 5. Use and refresh: The app calls FHIR with the token, checks the granted scopes before each feature, and refreshes or relaunches when the token expires.
Treat the iss value as untrusted input. Check it against the list of organizations you have agreed to serve before redirecting anywhere, so a crafted launch link cannot send your users to a fake authorization server.
Test the failure branches as well: a user who declines access, an expired code, a launch value that was already used, and a token granted with fewer scopes than requested. Each one should end on a clear message, not a blank frame inside the chart.
Per-organization endpoints and app activation
Each Epic customer runs its own FHIR server, so every health system has its own FHIR base URL. open.epic publishes an endpoint directory, and Epic's guidance is to download that endpoint information on a schedule, such as weekly, and host it yourself rather than querying it at run time.
Registration on Epic on FHIR creates the app record that holds the client ID, redirect URIs and the APIs the app uses. Testing starts against Epic's public sandbox and its published test patients. Production is a separate decision made by each Epic organization, which reviews the app and switches it on in its own environment.
Build for that from the start. Store per-site configuration for the base URL, enabled APIs, local identifiers and any site-specific scopes, so adding a second health system is a configuration change and a test run, not a code release.
Expect organizations to enable different subsets of APIs. A resource that returns data in the sandbox can be switched off at one site, so every feature needs a defined behavior when its API answers with an authorization error.
What can an Epic SMART app read and write?
An Epic SMART app can read the certified US Core data the organization exposes, and it can write only through specific Epic APIs the organization enables. The certified API under 45 CFR 170.315(g)(10) covers reads and excludes writes, so filing data back depends on Epic's additional APIs.
- Reads: Patient, Encounter, Condition, Observation, MedicationRequest, AllergyIntolerance and the other US Core profiles, within the scopes the token grants.
- Writes: Epic documents create APIs for some resources, for example Observation.Create for filing remote monitoring vitals. Each write API has to be listed on the app record and enabled by the organization.
- Population data: Backend clients can run a FHIR Bulk Data export against a Group, poll the status URL and download the result as NDJSON files.
- Errors: Failed calls return an OperationOutcome. Log its issue codes, not the request body, and show the user a message that names what is missing.
Where event data fits
A SMART app pulls data when a user or a job asks for it. When the product must react to every admission, order or result as it happens, plan that feed as an HL7 v2 interface built by the health system's team in Bridges.
FHIR subscriptions exist in the standard, but availability for a given event varies, so confirm in writing what the specific Epic organization offers before designing around one. Many products pair an HL7 v2 event feed with a SMART app for work in the chart.
Standards behind an Epic SMART app
Most of an Epic SMART integration rests on public standards and federal certification rules, which helps when a health system's security team asks why the app works the way it does. These are the statements worth citing.
- ASTP/ONC lists the HL7 SMART App Launch Implementation Guide Release 2.0.0 and US Core 6.1.0 among the standards for the 45 CFR 170.315(g)(10) certification criterion.
- ASTP/ONC states that (g)(10) requires API-enabled read services for single and multiple patients and specifically excludes write capabilities.
- The HL7 SMART App Launch guide defines the EHR launch, standalone launch and backend services flows, including the launch, iss and aud parameters.
- open.epic publishes a directory of Epic organizations' FHIR endpoints and advises apps to download and re-host that information rather than query it at run time.
- Epic on FHIR documents filing remote patient monitoring vitals either through HL7 v2 or through the Observation.Create API.
Epic go-live checklist
Run this checklist before the first Epic organization switches the app on in production. Each item can be shown to the health system's reviewers.
- Launch types: Each launch type is registered as its own client with the smallest scope set that works.
- Discovery: Authorize and token endpoints come from the SMART configuration at the iss URL, and unknown iss values are rejected.
- PKCE and state: Every authorize request uses PKCE and a state value checked on return.
- Per-site configuration: Base URL, enabled APIs and local identifiers live in configuration, not code.
- Missing APIs: Every feature has a tested behavior for an authorization error or an empty result.
- Tokens: Access tokens stay in memory or an encrypted store, never in logs, analytics or browser storage that outlives the session.
- Writes: Each write has a clinical owner at the site and a test that shows exactly where the data appears in the chart.
- Events: Any event-driven feature has a confirmed source, usually an HL7 v2 interface, before it is promised.
- Monitoring: Launch failures, token errors and authorization errors are counted per organization and alert a named owner.
How Agnotic can help
The hard part of an Epic app is rarely the first sandbox call; it is the second and third health system, each with its own endpoint, enabled APIs and review. Agnotic Technologies builds Epic SMART on FHIR apps with that in mind: launch and discovery handling, PKCE, per-organization configuration, US Core reads, the Epic write APIs a workflow needs, and Bulk Data jobs for population work.
When a product also needs event feeds, Agnotic designs the HL7 v2 side with the health system's interface team, so the app and the feed share one patient and encounter model.
Plan your Epic SMART on FHIR app with Agnotic
Explore Epic integration, or browse more articles in our FHIR hub.
Related reading on Agnotic
Continue with SMART on FHIR OAuth scopes, Epic Bridges integration, Epic integration strategies and FHIR subscriptions.
