Contact Us

Contact Us

Fetching User and Location Info at EPIC SMART on FHIR App Launch

Options for Fetching User and Location Info at EPIC SMART on FHIR App Launch

Your SMART app gets launched by Epic and the control is now passed to your app. In this article, we will go through the entire process of fetching user and location info at EPIC SMART on FHIR app launch. There is an Auth token passed to your app but it does not tell you exactly who the user is if the user is a doctor, an admin user, or someone else. It also does not tell you which department, location, the user is from and other similar user levels pertinent info. Our customers usually ask us how they can identify the user and use that info to match a user within their system. Or use this info to perform a session injection into their system for the right user.

We now see how to fetch user, department, etc, information from Epic.

Ways to Fetching User and Location Info at EPIC SMART on FHIR App Launch

So there are four ways we can get the provider information, department/location information in SMART on FHIR launched in the Epic environment.


1. Helper API (For versions `Epic 2018` and later):


For versions `Epic 2018` and later a private helper API is available that can be used to get the authenticated user’s information from the SMART on FHIR app.

This API is only available in the Garden and Terrace programs.


2. Fetch Encounter FHIR Resource (For versions earlier than Epic Nov 2019):


At launch time, the patient context and encounter context is passed on to the SMART app. One can fetch the Encounter resource and from there can fetch the practitioner, department/location, diagnosis, etc. There is a cost of 0.9 cents for the encounter resource read API call.


3. Token Library ie Context Tokens (For versions earlier than Epic Nov 2019):


Epic allows hospitals to configure different tokens from its Token Library. One can select any number of these tokens that get passed to a SMART app at launch time and there is no extra Epic charges for including these tokens, initially or on each launch. However, the hospital where the app will be hosted will require these tokens to be configured for your SMART app.

Some of the tokens that we can use are as following:

A: For Getting the Department:

%ENCDepID% (For Department of the order/encounter)
Or %ENCFACDEA% For DEA # of Encounter Department
Or %ENCFACNPI% NPI of the Encounter Department.
Or %ENCFACNPINAME%. Patient Encounter Department Name

B: For Getting User Name:

C: For User NPI

D: User ID For Non NPI users

E: Provider Type/Role

Please note that this option is only available with the EHR Launch of Epic with OAuth2 Context Tokens.

Here is the detail of all the tokens available that can be passed in.


4. ID_TOKEN (For Epic versions `November 2019` and later):

For Epic versions `November 2019` and later, There are two tokens that are passed at the SMART on FHIR launch time instead of just the access token:

A: access token

B: id_token

id_token is only available in versions `November 2019` and later.`id_token` is passed to the application that can be used to retrieve the authenticated user’s information without calling any API.

This JWT token, when decrypted gives us following info:



So with that info available, we can go fetch the Practitioner and PractitionerRole resources through FHIR and fetch the Practitioner NPI, Department, etc.

Planning to convert your web application to a SMART on FHIR app hosted in the Epic, Cerner or AllScripts environment? 

We can help! Find out more in a FREE 30 minutes introductory call. 

Schedule Here