Epic FHIR authentication

Connect UiPath to your own Epic instance in Automation Cloud using OAuth 2.0 client credentials with a SMART on FHIR Backend Services app.

Creating an Epic FHIR connection involves both your Epic team and your UiPath organization administrator. Your Epic team prepares the Epic environment, and you then enter the resulting values in Integration Service.

Prerequisites

UiPath publishes two registered Epic applications, Production and Non-Production, and their Client IDs are built into the connector. Your Epic organization downloads the UiPath app into its environment, and you then select which of the two a connection uses.

Note:

Your organization does not register its own Epic app. Registering your own Epic app and supplying its Client ID is not supported.

Client IDs

Provide these to your Epic representative when you request the app. A Client ID identifies an application and is not a secret.

Environment	Client ID
Production	5174fc67-b03a-4069-a2e3-de2a7c7f66ec
Non-Production	8f79c643-ffb6-4b1c-8988-3d15684841a5

What you need

• The UiPath Epic app downloaded into your Epic environment. Your Epic team requests it through Epic's app request process, searching by the Client ID for your target environment. Epic's App Creation & Request Process covers this in its Requesting An App and Downloading Client Records sections, and the connector is also listed on Epic Showroom.
• The FHIR API root and the token endpoint for your Epic instance. See Finding the Epic instance URLs.
• A private key whose public half is registered for the app in your Epic environment. Generate an RSA key pair, 2048-bit minimum and 4096-bit recommended. The connector accepts both PKCS#8 PEM and JSON Web Key (JWK) JSON. You keep the private half and enter it in the connection, where it is stored encrypted and never returned. For an example using OpenSSL, see Epic's Creating a Key Pair documentation.

Start with non-production. Epic requires an app to be downloaded and activated in a non-production environment before it can be used in production. Most organizations use both Client IDs over the life of an integration, which is why the connection form provides an Epic App picker rather than a fixed value. Plan for two connections.

Important:

Confirm that every API you plan to call is authorized for the app in your environment. This is the most common reason a connection authenticates successfully but returns no usable data. See Access was withheld in the activities documentation.

Setup overview

The following four steps are in order. Steps 1 and 2 depend on your Epic release schedule, so allow the most time for them.

1. Ask your Epic team to download the UiPath app. They need the Client ID for the environment you are targeting, from the Client IDs table. Non-production comes first.
2. Register your public key and confirm API access. Your Epic team registers the public half of your RSA key pair against the app, and confirms that every FHIR API your automation will call is authorized for it.
3. Collect the Epic instance URLs. You need the FHIR API root and the OAuth 2.0 token endpoint. See Finding the Epic instance URLs.
4. Create the connection in Integration Service. The values from the previous steps go into the connection form, along with your private key. See Adding the Epic FHIR connection.

Finding the Epic instance URLs

The connection asks for two Epic instance URLs and does not derive either one from the other. Your Epic technical contact can supply both, and both can be confirmed from your own Epic instance.

The common URL pattern

Most Epic organizations follow the same shape, built from a single instance root:

FHIR Base URL        https://{host}/{instance}/api/FHIR
Token Endpoint URL   https://{host}/{instance}/oauth2/token

For Epic's public sandbox, whose instance root is https://fhir.epic.com/interconnect-fhir-oauth, that gives:

FHIR Base URL        https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR
Token Endpoint URL   https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token

Warning:

Treat this pattern as a likely answer, not a rule. Some Epic deployments host the token endpoint on a different path, or on a different host entirely, and the resulting 401 looks exactly like a bad key. Confirm the endpoint from your instance's metadata document.

Confirming the Epic instance URLs

Your Epic instance publishes its own capability statement, and it requires no credentials. This is the authoritative answer for the token endpoint.

Request the metadata document, substituting your FHIR base URL:

GET https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/metadata
Accept: application/fhir+json

The token endpoint is in the SMART oauth-uris extension, under rest[0].security.extension:

{
  "url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
  "extension": [
    { "url": "authorize", "valueUri": "https://.../oauth2/authorize" },
    { "url": "token",     "valueUri": "https://.../oauth2/token" }
  ]
}

Take the valueUri whose url is token. That is your Token Endpoint URL. The address you called, minus the trailing /R4/metadata, is your FHIR Base URL.

Note:

Add Accept: application/fhir+json. Without it the response comes back as XML.

Where to find your instance root

Epic's public endpoint directory at open.epic.com/MyApps/Endpoints lists the FHIR URL for every organization. Those entries include the release segment and end in /api/FHIR/R4. The connector adds the release itself, so remove that last segment and enter the URL ending in /api/FHIR.

Adding the Epic FHIR connection

Five fields are required, and one is optional.

Field	Required	What to enter
Epic App (Client ID)	Yes	The UiPath Epic app this connection authenticates as. Both Client IDs are pre-filled, so choose Production or Non-Production to match the environment your Epic instance URLs point at.
FHIR Base URL	Yes	The FHIR API root of your Epic instance, without the release segment. For example, https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR.
Token Endpoint URL	Yes	Your Epic deployment's OAuth 2.0 token endpoint. See Finding the Epic instance URLs.
FHIR Version	Yes	R4, the only available option.
Private Key	Yes	The PEM or JWK JSON private key matching the public key registered for this app in your Epic environment.
Key ID (kid)	No	The key ID from your hosted JSON Web Key Set (JWKS). Leave it blank for a PEM uploaded directly, which Epic needs no ID to select.

To create the connection:

1. Select Orchestrator from the product launcher.
2. Select a folder, and then navigate to the Connections tab.
3. Select Add connection.
4. Select Epic FHIR from the connector list. You can use the search bar to find the connector.
5. Enter the values from the preceding table, and then select Connect.

Where available, select the menu next to a field and choose Use credential asset or Use Orchestrator asset to reference an Orchestrator asset instead of entering the value directly. For more information, see Use credential assets for connections.

What happens when you connect

Creating a connection mints a token and issues one authenticated, read-only request against Practitioner in your Epic instance.

Result	Meaning
Connection created	Your credentials are valid.
401, connection rejected	The credentials are incorrect. Check for a key mismatch, a wrong kid, the wrong Epic App, or a token endpoint that does not belong to your organization.
400 or 403, connection still created	The token was accepted. Either your organization restricts that particular search, or the app is not authorized for Practitioner.

Note:

Epic validates the bearer token before it inspects the request, so a 400 or 403 response is only possible once a token has been accepted. Treating either as a failure would reject connections whose credentials are correct.

Connection limitations

• Both URLs must be supplied. The connector asks for the FHIR API root and the token endpoint separately and derives neither from the other. Integration Service runs no connector code before the token is requested, so the token endpoint cannot be discovered from your instance's /metadata document at connection time, even though that document is the authoritative source.
• UiPath-registered Epic app only. Connections authenticate as one of UiPath's two registered Epic apps. Using an Epic app registered by your own organization is not supported.
• The private key is never returned. It is stored encrypted, and no activity returns it.

For limitations that apply to the activities rather than the connection, see Known limitations.

Connection failures

Symptom	Likely cause
401 when creating the connection	The private key does not match the public key registered for the app, the kid is incorrect, or the wrong Epic App is selected for this environment.
401 when every value appears correct	The token endpoint. Confirm it from your instance's /metadata document rather than assuming the /oauth2/token pattern.
The token is issued, but calls return 404	The FHIR Base URL includes or omits a tenant path segment, or still carries the trailing /R4. Confirm the exact endpoint with your Epic contact.
Works in non-production, 401 in production	The Epic App picker is still set to Non-Production, or your production app has not yet been downloaded and activated.

Roughly one Epic organization in seven does not follow the /oauth2/token pattern, which makes the token endpoint the first value to verify when everything else looks correct. See Finding the Epic instance URLs.

For errors encountered while running activities rather than while creating the connection, see Troubleshooting in the activities documentation.