Epic EHR configuration

This page describes how to register and configure an Epic app before you create the Epic EHR data store. Your organization registers its own Epic app. Your Epic analyst usually completes these steps.

Register the Epic app

Register an app for Gemini Enterprise in Epic on FHIR, and make it available in your Epic environments. Use the following settings:

Setting Value
Application Audience Clinicians or Administrative Users
Incoming APIs The R4 APIs listed in Enable the Epic APIs
Outgoing APIs None
Will this app register dynamic clients? No
Is Confidential Client Yes
Requires Persistent Access Yes
Uses Rolling Refresh Tokens Yes
JWK Set URL Leave blank
SMART on FHIR Version R4
SMART Scope Version SMART v1
FHIR ID Generation Scheme Use 64-Character-Limited FHIR IDs for USCDI FHIR Resources

Your organization's persistent access settings for the app determine how long a user's authorization lasts. When it ends, the user authorizes the connector again.

Set the redirect URIs

In the app, register both of the following redirect URIs exactly as shown:

  • https://vertexaisearch.cloud.google.com/oauth-redirect
  • https://vertexaisearch.cloud.google.com/console/oauth/default_oauth.html

Enable the Epic APIs

In the app, enable the R4 read and search APIs for the following FHIR resources: Patient, Observation, Condition, MedicationRequest, AllergyIntolerance, DiagnosticReport, DocumentReference, Binary, Encounter, ServiceRequest, Coverage, Immunization, and Procedure.

Some resources, such as Observation and Condition, have a separate API for each category, for example labs and vital signs. Enable the categories that you want users to query. Don't enable write APIs.

If an API isn't enabled, only the actions that use it fail.

Get the client ID and client secret

Epic issues a non-production client ID and a production client ID for the app. Use the client ID that matches the Epic environment that your URLs point to. Because the app is a confidential client, it also has a client secret. You enter the client ID and client secret when you create the data store.

Find your Epic endpoints

To create the data store, you need three URLs from your Epic environment: the FHIR R4 base URL, the authorize URL, and the token URL. Your Epic analyst can provide them. Your organization's SMART configuration, at FHIR_BASE_URL/.well-known/smart-configuration, also lists the authorize URL (authorization_endpoint) and the token URL (token_endpoint). Replace FHIR_BASE_URL with your FHIR R4 base URL.

Enter each URL with https:// and without a trailing slash. For example, Epic's public sandbox uses the following URLs:

URL Epic sandbox example
FHIR R4 base URL https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
Authorize URL https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize
Token URL https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token

Troubleshoot

The following table lists common issues and how to resolve them:

Issue Resolution
The console shows one of the following messages:
  • "Epic FHIR R4 URL must be an https:// URL without a trailing slash."
  • "Epic Authorize URL must be an https:// URL without a trailing slash."
  • "Epic Token URL must be an https:// URL without a trailing slash."
 Enter the URL with https:// and without a trailing slash.
The console shows "Failed to obtain refresh token." In the Epic app, select Is Confidential Client and Requires Persistent Access, and save the changes. Then, in the Google Cloud console, click Verify Auth again.
Epic reports that the redirect URI doesn't match. Register both redirect URIs exactly as shown in Set the redirect URIs.
Epic shows "Invalid OAuth 2.0 request" during sign-in. Each Epic sign-in link works only once, so reloading the sign-in window shows this error. Close the window, and start the sign-in again without reloading. If the error continues, check that the app has the APIs for the requested scopes.
Epic returns invalid_client. The client ID or client secret is wrong, has extra spaces, or belongs to the other Epic environment. Enter the client ID and client secret for the environment that your URLs point to.
The sign-in window doesn't return to Gemini Enterprise, or the connector isn't authorized after sign-in. Close the sign-in window, reload Gemini Enterprise, and authorize the connector again.
One action fails, and other actions work. The Epic API for that action isn't enabled. Enable it in the app, and then have the user authorize the connector again.
Gemini Enterprise says "I'm sorry, it seems you are not allowed to perform this operation. Please contact an administrator." to a user who authorized the connector before. The user's Epic authorization has ended. The user authorizes the connector again.
Gemini Enterprise doesn't find a patient by name. Add the birth date, or use the MRN or Epic patient ID.
Gemini Enterprise says that some records couldn't be retrieved. Epic security withholds these records from the user. Users see only the records that Epic allows them to see.
The text of a report or note isn't available. The document is a PDF or another format that the connector can't read. Open the document in Epic.
Authorization keeps failing in one app only. Remove the Epic EHR data store from the app, add it back, and authorize the connector again.

What's next