Contact Us

Contact Us

Integrating SMART on FHIR App With EPIC

What is SMART?

SMART(Substitutable Medical Apps, Reusable Technology) is an App Platform for Healthcare. Moreover, 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.

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 operational on all the healthcare computer systems. 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.

Integrating SMART app with EPIC

Lets first understand the following two related concepts for EPIC as these are used in coming sections.

  • AppOrchard

App store for EPIC like Apple or Android where you can publish your patient or provider facing apps for users. Once the user is interested in your app there are steps needed to integrate that app into EPIC in user premises. So AppOrchard is 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

  • MyApps

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

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

Here is snap from MyApps registration screen:

  • EPIC Launch Sequences

As per SMART standards, EPIC integration allows to launch the app in two SMART supported contexts:

          1. Launch with EHR context

You can deploy your application at any server and using EPIC Launch Pad you can launch it in EHR context.



And in launch.html :

html code

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
    • iss contains Epic’s base FHIR server URL

Your web application should query Epic’s FHIR server’s metadata endpoint ( 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 given guidelines.  See image below from launch.html file:

my apps code
Below are some details about above code snippet:

  • You have SMART web app created and deployed on some 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.
  • Next important piece of code is client_id While testing the app in a non-production environment, make sure to use NONPROD CLIENT ID that is given on the EPIC registration screen. The other ID listed as CLIENTID on 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 its PROD or NONPROD


Here is what happens when you do it:

  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 know this as we registered our application via MyApps).
  2. Since we are testing a standalone context and authentication is not yet made; FHIR server redirects you to provider facing app. In EPIC sandbox or public servers it’s EPIC MyCharts application for authentication as shown below:

Integrating SMART app with EPIC

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

epic smart on fhir

4. Finally, It redirects to the URL in variable redirect_url configured in the EPIC registration screen and launch.html file. Here in 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

The code snippets from SMART app Technosoft developed. We have used SMART on FHIR JS client in an application. It handles lots of stuff automatically for you. For example when launching in EHR context; it automatically gets the parameters passed in query string including FHIR server URL.  After you have the FHIR server URL, call conformance API to know authorization endpoints. Then hit the authorization server sending token to authorize your app. If a successful authorization server will send the access token back. This access token can be used to call the FHIR APIs to get patient info.


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

To discuss our services, expertise and how we can help you, please contact us.