Epic SMART on FHIR app development · United States
We build SMART on FHIR apps that launch inside Epic: clinician apps embedded in Hyperspace and Hyperdrive, patient apps that sign in with MyChart, backend services and CDS Hooks. Launch context, scopes, token handling and the customer's review are designed in from the first sprint, so the app that works in the Epic sandbox is the app the health system switches on.
Plan my Epic SMART appCompare launch typesFor healthcare product teams and the customers who use their integrations.
SMART App Launch 2.0 · EHR launch · Standalone launch · PKCE · SMART v2 scopes · OpenID Connect · CDS Hooks · FHIRcast
Updated September 2026
Epic sends launch and iss to your launch URL from the patient chart.
Read .well-known/smart-configuration, request scopes with aud and PKCE.
The token response carries patient, encounter and the user's fhirUser.
Epic's guideline for embedded apps, with clear states for missing context.
Illustrative implementation plan · no patient data
Your starting point
Epic SMART on FHIR app development builds applications that authorize with Epic through OAuth 2.0 and OpenID Connect and then call Epic's FHIR APIs with the context of the current patient and user. Nirmitee picks the launch type for each user, registers the app on fhir.epic.com with the right SMART v1 or v2 scopes, builds the launch, token and session handling, and tests the unhappy paths: missing context, expired sessions, denied scopes and a clinician switching patients. We then take the app through the health system's review and activation, so it goes live inside the chart rather than stopping at a sandbox demo.
Clinical AI, decision support, care coordination, patient engagement and specialty workflow products that need to run inside Epic or sign patients in with MyChart.
Epic sends launch and iss to your launch URL from the patient chart.
EHR launch apps embedded in Hyperspace and Hyperdrive, standalone patient and clinician apps, backend services and CDS Hooks services.
Read .well-known/smart-configuration, request scopes with aud and PKCE.
A SMART app activated at your first Epic customer, with launch, scope and session behavior documented for the next one.
The token response carries patient, encounter and the user's fhirUser.
SMART launch types
The launch type decides the sign-in, the context you receive and how a health system approves the app. Pick it per user, not per product.
| Launch type | Who starts it | Epic specifics | What we design for |
|---|---|---|---|
| EHR launch (embedded) | A clinician, from the patient chart in Hyperspace or Hyperdrive | launch and iss on the launch URL; aud required since May 2023 when launch context is in scope; test with LaunchPad and the Hyperspace Simulator | Patient and encounter context, stale-patient protection when the clinician switches charts, and load time under 1.5 seconds |
| Standalone clinician launch | A clinician, from your app | Epic user login, fhirUser and openid, confidential client with a secret or signed JWT | Choosing the organization, session timeout on shared workstations and a patient picker |
| Standalone patient launch | A patient, signing in with MyChart | Public client with PKCE (supported since Epic August 2019), refresh tokens, auto-distribution for read-only USCDI apps | Consent, reconnection, token refresh and choosing among the 479 Epic R4 endpoints in the public directory |
| Backend services | A server process, no user | client_credentials with a signed JWT whose exp is at most 5 minutes out; JWK Set URL required from the May 2026 Epic version | Key rotation, per-customer credentials and throttling |
| CDS Hooks | Epic, when the clinician opens a chart or signs an order | patient-view, order-select and order-sign hooks; suggestions create unsigned orders and problems | Card latency, relevance and the SMART app a card can launch |
| Context sync (FHIRcast) | Hyperdrive, as the clinician moves between patients | Subspace is Epic's FHIRcast implementation, with concise events from August 2026 | Keeping a side-by-side app on the same patient as the chart |
Launch facts from fhir.epic.com OAuth 2.0 and testing documentation, checked 25 September 2026.
Find your workflow
Each app type carries its own authorization, review and support work. We scope it before the first estimate.
Decision support, AI summaries, specialty documentation and care coordination launched from Hyperspace or Hyperdrive with the patient already in context.
EHR launch · launch/patient · launch/encounter · fhirUser · openid · Hyperdrive
Companion, RPM and engagement apps where the patient connects their Epic record with their MyChart credentials.
Standalone launch · PKCE · offline_access · refresh tokens · patient/*.rs (SMART v2)
Server-side jobs that sync data, run models or feed a warehouse without a user present.
SMART Backend Services · client_credentials · RS384 JWT · JWK Set URL
Cards and suggestions at the moment of ordering, including coverage and prior authorization checks for CMS-0057-F.
CDS Hooks 2.0 · patient-view · order-select · order-sign · Da Vinci CRD
A shared discovery, PKCE, token and chart code path with each vendor's scope rules, token lifetimes and write quirks kept in configuration.
SMART App Launch 2.0 · Epic scope grant · Oracle scope intersection · per-vendor config
When your product is the EHR or data platform, we build the SMART server side: authorization server, scopes, launch and token introspection.
SMART App Launch 2.0 · token introspection · ONC (g)(10) · Inferno
Choose the right connection
Many products use two: an embedded app for clinicians and a backend service for data sync, or a CDS Hooks card that launches the app.
Many products use two: an embedded app for clinicians and a backend service for data sync, or a CDS Hooks card that launches the app.
Load time, stale context and the customer's clinical review
| Approach | Use it when | How it reaches customers | Watch for |
|---|---|---|---|
| Embedded EHR launch app | Clinicians act inside the chart and need patient context | Customer request and build of the launch in Hyperspace or Hyperdrive | Load time, stale context and the customer's clinical review |
| Standalone patient app | Patients connect their own records from your app | Auto-distributed when read-only and USCDI-only; otherwise customer approval | Refresh tokens, reconnection and organization selection |
| Standalone clinician app | Clinicians work in your product and pull Epic data on demand | Customer approval of the client and its APIs | Credential handling on shared devices and session length |
| Backend service | No user is present: sync, analytics, AI pipelines | Customer approval plus key provisioning per site | Key rotation, JWK Set URLs and load on the customer's database |
| CDS Hooks service | Guidance must appear at chart open or order sign | Customer configuration of the hook and its triggers | Response time and alert fatigue |
Need the API detail behind these apps? See Epic FHIR API integration services. Building for phones? See Epic mobile app and MyChart integration.
Decisions before development
These rules come from Epic and the health system. We design with them rather than discover them at activation.
In our run, Epic ignored the requested resource scopes and granted what the app registration lists: we asked for openid fhirUser and received 84 scopes. The registration is the real permission list, so it only names APIs the app uses.
Epic apps use SMART v1 scopes (.read, .write) or SMART v2 scopes (.c .r .u .d .s). ONC's certification rules adopted SMART App Launch 2.0.0 and let 1.0.0 expire on 1 January 2026, so new apps start on v2.
After Ready for Production only redirect URIs and JWK Set URLs change; anything else needs a new app record. We finalize APIs, launch type and scopes before that step.
Only read-only patient apps that use USCDI APIs are auto-distributed. Clinician, backend and write apps go through each health system's request and security review.
Epic's guidelines ask embedded apps to load in 1.5 seconds on average, never consistently over 5, with less than 1% downtime. We budget for it in the architecture.
A Showroom listing is optional and not required to connect. Connection Hub needs your product live with at least one Epic customer.
What we define together
Once paid, everything below is yours and lives in your repository, along with all of your data. We keep our reusable tools and open-source parts.
Each user journey with its launch type, context parameters, SMART scopes and the fallback when context is missing.
The fhir.epic.com app record, client IDs, redirect and launch URLs, JWK Set URLs and the justification for every API.
Launch, authorization, token refresh, session and logout handling with the clinical or patient experience on top.
Automated tests for denied scopes, expired tokens, cancelled consent, missing encounter and patient switching, run against the Epic sandbox.
Architecture, data flow, scopes, PHI handling and hosting answers ready for each health system's questionnaire.
Per-site launch configuration, key provisioning, smoke tests and the escalation path after go-live.
Delivery, with ownership
The build runs on our plan; activation runs on the health system's review and change calendar, which we track as named dependencies.
User journeys, launch types, scopes and a registered app on fhir.epic.com.
Weeks 1 to 2
Working launch and FHIR reads or writes against the Epic sandbox, tested with LaunchPad and, for embedded apps, the Hyperspace Simulator.
Weeks 2 to 8
Security questionnaire, launch configuration in the customer's non-production environment, clinical validation and production cutover.
Weeks 6 to 16, paced by the health system
Repeatable site activation and, when you are ready, a Showroom Connection Hub listing.
After the first go-live
The estimate structure
We give a fixed scope after launch design. These are the factors that move it.
One embedded clinician app is smaller than an app that also supports patient standalone launch and a backend service.
Read-only apps avoid write validation and clinical review; write-back adds API-specific rules and review.
A single summary card differs from a full workflow app with its own data model inside the chart.
Hooks and FHIRcast context sync add latency engineering and customer configuration.
Supporting Oracle Health or other EHRs alongside Epic adds vendor configuration and testing, not a second app.
Any Epic Vendor Services membership, Showroom listing fee and the health system's API subscription are separate from our engineering and listed in the estimate.
Engagement options
Choose the starting point that matches your access, existing product and delivery needs.
For an uncertain route or missing access. Define the workflow, test the difficult assumptions and produce a scope with named dependencies.
For a validated operation contract. Agree the connector, application changes, acceptance evidence and customer rollout milestones.
For an existing connection. Prioritize new workflows, diagnose recovery gaps and define monitoring and support ownership.
Evidence you can check
Client names are withheld; each item is a real engagement or a public repository you can inspect.
Our multi-EHR SMART app runs discovery, PKCE and token exchange against both vendors from one code path, reads the chart and files a vital-sign Observation that returns 201 and reads back. It records what differs: Epic granted the scopes on the registration (we asked for openid fhirUser and received 84), Oracle Health granted only the intersection, and Oracle access tokens lasted about 570 seconds.
A FHIR R4 server with SMART App Launch that passed 47 of 47 ONC (g)(10) SMART standalone patient tests in Inferno. It is the same authorization and launch contract Epic and Oracle Health implement.
Coverage Requirements Discovery over CDS Hooks, Documentation Templates and Rules, and Prior Authorization Support, tested with the Inferno kits. These are the flows behind Epic's CMS-0057-F payer APIs.
Scheduling, charts, care plans and billing on a FHIR R4 server with no private database. Clinicians sign in through a PKCE OAuth 2.0 flow and an OAuth token exchange bridges the organization's single sign-on to the FHIR server.
Before you commit
SMART on FHIR is the HL7 standard that lets an app sign in through OAuth 2.0 and OpenID Connect and call FHIR APIs with the current patient and user as context. Epic supports it for clinician and patient apps, for EHR launch and standalone launch, and for backend services without a user.
An EHR launch starts your app from inside Epic. The clinician opens it from the patient chart, Epic calls your launch URL with launch and iss parameters, your app requests authorization with those values, and the token response returns the patient, encounter and user context so the app opens on the right patient.
In an EHR launch the user starts in Epic and Epic supplies the context. In a standalone launch the user starts in your app, signs in with Epic or MyChart credentials and chooses the patient or organization. Clinician tools usually embed; patient apps usually launch standalone.
Epic supports SMART v1 scopes and SMART v2 scopes with create, read, update, delete and search permissions, selected when you register the app. ONC's certification rules require SMART App Launch 2.0.0 for certified APIs since 1 January 2026, so we build new Epic apps on v2.
Register the app on fhir.epic.com, build against the Epic sandbox and test EHR launches with LaunchPad. Vendor Services adds the Hyperspace Simulator and Hyperdrive testing harness. The sandbox is refreshed every Sunday evening Central Time, so test data is reseeded each week.
No central approval is needed to connect. Each health system approves the apps that connect to its instance, except read-only USCDI patient apps, which Epic distributes automatically. A Showroom listing is optional marketing; Connection Hub needs one live Epic customer.
Cost follows the launch types, whether the app writes back, the depth of the user experience, CDS Hooks or context sync, and how many EHRs you support. We fix the scope after a short launch design and list third-party fees separately.
A focused embedded app is typically built and sandbox-tested in 6 to 8 weeks. The first customer then adds its security review, launch configuration and clinical validation, commonly several months. Each later site reuses the same app and runbook.
Epic grants the scopes on the app registration regardless of what the authorization request asks for. In our run, requesting openid fhirUser returned 84 scopes. Keep the registration limited to the APIs you use; each health system reviews that list.
Epic's documentation shows access tokens that expire in about an hour. Patient apps that need longer access use refresh tokens, and native apps use PKCE. Oracle Health tokens lasted about 570 seconds in our run, so a multi-EHR app refreshes per vendor rather than on one timer.
Yes, through Epic's write APIs, for example vital signs, plain-text clinical notes, problems and allergies. Each needs its scope on the registration and has its own rules, such as an Encounter reference for vitals. CDS Hooks suggestions can also create unsigned orders for the clinician to sign.
Yes. We build one discovery, PKCE, token and chart code path and keep each vendor's quirks in configuration. Epic grants registered scopes while Oracle Health grants the intersection of requested and registered scopes, and write rules differ per resource, so both are tested separately.
Next useful step
In 30 minutes we pick the launch type for each user, list the scopes and APIs, and outline the path to your first Epic customer.
Plan with the right evidence
Review the current vendor documentation alongside your customer's requirements. The delivery plan records the operations tested, environment and outstanding approvals.
SMART App Launch specification ↗Epic OAuth 2.0 and SMART guide ↗Epic testing guide and LaunchPad ↗Epic patient-facing app distribution ↗Epic CDS Hooks documentation ↗Epic developer guidelines ↗45 CFR 170.215 API standards ↗CDS Hooks specification ↗Epic, MyChart, Hyperspace and Hyperdrive are trademarks of Epic Systems Corporation.
Talk through your requirements
Tell us who uses the app, where they start and the data it reads or writes. We reply with the launch pattern, scopes and next practical step.
From our YouTube channel
Explore the workflows and decisions behind this service. Demonstrations and recorded discussions have the scope described in each video.
Understand SMART on FHIR and how it fits an EHR-connected product.
Epic public sandbox sign-in, chart reads and vital-sign write-back with synthetic test patients.
