Epic SMART on FHIR integration With Epic

Integrating SMART on FHIR Apps with Epic: From App Orchard to Epic Showroom

Integrating a SMART on FHIR app with Epic requires navigating the Epic Showroom (formerly App Orchard) and registering via the Connection Hub. The technical core involves a secure OAuth 2.0 / OIDC handshake and mapping clinical data to the HL7 FHIR R4 standard. Technosoft specializes in the full integration lifecycle, from Sandbox testing to production go-live in both Hyperspace and Hyperdrive environments.

Since 2009, Technosoft Solutions has pioneered healthcare interoperability. We have guided developers and hospital systems through every evolution of the Epic ecosystem. Whether you are still referencing the App Orchard or moving into the modern Epic Showroom and Connection Hub, our team ensures your SMART on FHIR application meets 2026 standards for security, performance, and clinician workflow.

What is SMART?

SMART(Substitutable Medical Apps, Reusable Technology) is an App Platform for Healthcare. SMART Health IT is an open, standards-based technology platform that enables innovators to create apps that seamlessly and securely run across the healthcare system. Using an electronic health record (EHR) system or data warehouse that supports the SMART standard, patients, doctors, and healthcare practitioners can draw on this library of apps to improve clinical care, research, and public health. In this article, we will go into detail about developing an Epic SMART on FHIR integration with Epic, including App Orchard publishing and OAuth authentication.

What is SMART on FHIR?

SMART (“Substitutable Medical Applications, Reusable Technologies”) on FHIR is an open, HL7 FHIR standard-based platform that enables developers to create apps that can securely and seamlessly be integrated into all the major EHRs in the industry. SMART on FHIR is a set of open specifications to integrate apps with Electronic Health Records, portals, Health Information Exchanges, and other Health IT systems.

How a SMART on FHIR app works in Epic

Like all other major EHRs, Epic allows integration of SMART on FHIR apps within its EHR. A user of Hyperspace (Epic’s provider-facing software) can activate a third-party vendor’s SMART on FHIR app from within Hyperspace. The third-party SMART on FHIR app can be instantiated from the menu, left navigation bar, etc. When a SMART on FHIR app is instantiated, an authenticated token for access to an FHIR server, along with the FHIR server URL, is passed to the third-party app developer. The third-party App developer can query the authorized patient’s data from the FHIR server and use it in the SMART on FHIR app. For the user, the SMART on FHIR App is shown in an iFrame within the Hyperspace simulator and in ActiveX based web browser control in the Hyperspace Desktop Application.

Integrating SMART app with Epic

To integrate a SMART on FHIR app into the Epic EHR, one needs to register their app at Epic’s App store, App Orchard.  Let’s first understand the following two related concepts for EPIC, as these are used in the coming sections.

• AppOrchard

  
  

Epic has an App Store, App Orchard, where one can publish patient or provider-facing SMART on FHIR apps for users. Once the user is interested in a published app, there are steps needed to integrate that app into Epic on the user’s premises. AppOrchard is also the place where developers can learn about and access Epic’s APIs and list their apps for Epic community members to explore and acquire. To access, go to URL https://apporchard.epic.com.

• MyApps

  
  

It’s the place where you register your app with Epic that can later be deployed to AppOrchard or integrated into a hospital EHR directly. One must have a valid account at MyApps to register an application with Epic that can later be published to AppOrchard or can be integrated with the hospital EHR directly.

You can test your app without registering at MyApps (using Epic launchpad that runs the app in EHR launch context), but to test the app as a standalone, you need to code accordingly, so you have to register with MyApps to get the client_id used in the code. See the section below, “Epic Launch Sequences,” for more details on the code.

Here is a snap from the MyApps registration screen:

(Figure: Application registration screen on MyApps)

Epic Launch Sequences

As per SMART standards, Epic integration allows the launch of the app in three SMART-supported contexts:

1. Launch with EHR context

You can deploy your application to any server, and using Epic LaunchPad, you can launch it in the EHR context.

And in launch.html:

Make sure the client_id given in the code is exactly what we have on the MyApps registration screen. See ( Figure: Application registration screen on MyApps )

Here is what happens when you do it:

1. Epic will open your web app’s launch URL with at least two URL parameters:
   • launch contains a SMART on FHIR launch token
   • Epic’s base FHIR server URL

Your web application should query Epic’s FHIR server’s metadata endpoint (https://open-ic.epic.com/Argonaut/api/FHIR/Argonaut/metadata) to find Epic’s OAuth2 authorization and token endpoints.

2. In order to bind your web app’s session with the existing end-users’ EHR session, your app should redirect the browser to the Epic OAuth authorization endpoint with the following parameters:

response_type = "code"
client_id = client_id (defined above)
redirect_uri = redirect_url (defined in the above form)
launch = the launch token (as passed to your web app's launch URL)
state = <an opaque value used by the client to maintain state between the request and callback.>
scope = "launch" (this is necessary to indicate the app is launching from the EMR context to enable single sign-on)

Epic will then redirect to your provided redirect URL with an authorization code and the state parameter you provided.

3. Your web app should exchange the authorization code for an access token by posting the following parameters to Epic’s OAuth token service:

grant_type = "authorization_code"
code = the authorization code your web app received
redirect_uri = redirect_url (defined in the above form)
client_id = client_id (defined in the above form)

Epic will return an access_token. (In a production customer environment, a health system may configure additional SMART launch parameters, which will be presented to your app during an EHR launch alongside the access_token, just as a user parameter is presented from this internal environment.)

4. Your web app can use the time-limited access token to access Epic FHIR resources. Include the token as a “Bearer” token in the Authorization HTTP header as part of your RESTful queries.

2. Standalone application launch

To test your app as a standalone launch, there is no launchpad-like platform. You have to code as per the given guidelines.  See the image below from the launch.html file

Below are some details about the above code snippet:

• You have a SMART web app created and deployed on a server
• In your launch.html provide redirect_url and FHIR Server URL as shown below. Make sure this redirect_url is the same that you gave when registering the app on MyApps. See ( Figure: Application registration screen on MyApps )
• The server variable should be set to some public Epic FHIR server or one that your hospital has set up for you, not a PROD server URL.
• The next important piece of code is client_id. While testing the app in a non-production environment, make sure to use the NONPROD CLIENT ID that is given on the Epic registration screen. The other ID listed as CLIENTID on the Epic registration screen can only be used in a PRODUCTION environment. How to sense if we are in PROD or NonPROD env; is easy; check your FHIR Server URL set in a variable server; if it’s PROD or NONPROD

Here is what happens when the app is launched:

1. As you access your app launch.html in the browser, it hits the given FHIR server. This FHIR server validates the client_id with Epic (Epic knows this as we registered our application via MyApps).
2. Since we are testing a standalone context and authentication has not yet made, the FHIR server redirects you to the provider-facing app. In Epic sandbox or public servers, it’s the Epic MyCharts application for authentication, as shown below:

3. On a successful login, it takes you to the patient selection page. Selecting the required patient and clicking Allow Access allows Epic to exchange info with the SMART app, as shown below:

4. Finally, it redirects to the URL in the variable redirect_url configured in the Epic registration screen and launch.html file. Here is your index.html file. You will have patient context available and a token that you can use to call FHIR APIs to get patient-related data.

3. SMART on FHIR JS Client

When launching in the EHR context, the SMART on FHIR JS Client can automatically get the parameters passed in the query string, including the FHIR server URL.  After one has the FHIR server URL, it can be used to call the conformance API to know the authorization endpoints. Then the authorization server can be accessed, sending the token to authorize one’s app. If the call is successful, the authorization server will send the access token back. This access token can be used to call the FHIR APIs to get patient info from the FHIR server URL, and patient FHIR data can be served within the SMRT on the FHIR app or passed on to a third-party application for further workflow.

If you are not using the SMART on FHIR JS client, we have to handle all that stuff ourselves, and a guide is available or SMART on FHIR website and the EPIC sandbox website.

Frequently Asked Questions about SMART on FHIR Integration with Epic

Starting any Healthcare Integration Project? Get your questions answered in a free 30-minute consultancy!