Skip to main content

Authorization

Follow this guide to create a new EPIC EHR credential that will allow Nexla to authenticate to and exchange data with your Epic FHIR R4 API using secure backend OAuth 2.0 (JWT client credentials).
epic_ehr_auth.png

EPIC EHR

Prerequisites​

Epic uses the SMART Backend Services profile of OAuth 2.0 for system-to-system integrations. Instead of username/password, your application signs a JSON Web Token (JWT) with an RSA private key; Epic's authorization server validates the signature against the registered public key and returns a short-lived access token. You must complete the steps below in Epic's developer portal before configuring the credential in Nexla.

Register an App on Epic on FHIR​

  1. Navigate to Epic on FHIR and sign in (or create a free account) at fhir.epic.com.

  2. Click My Apps in the top navigation, then click Create to register a new application.

  3. Fill in the required details:

    • Application Name: Enter a descriptive name (e.g., Nexla Integration).
    • Application Audience: Select Backend Systems (for system-to-system flows).
    • Application Type: Select Confidential Client or Backend Services as appropriate.

  4. Under Authorized APIs / Scopes, select the FHIR resource scopes your integration needs. For read access, use system/<ResourceType>.read scopes (e.g., system/Patient.read, system/Observation.read). For write access, use system/<ResourceType>.write.

  5. Save the application. Epic will generate a non-production (Sandbox) Client ID and a production Client ID. Copy the appropriate Client ID for use in Nexla.

Generate an RSA Key Pair​

Epic's backend OAuth 2.0 flow requires your application to sign JWTs using an RSA private key. The corresponding public key must be registered with Epic.

  1. Generate a 2048-bit (or larger) RSA key pair using a tool such as OpenSSL:

    openssl genrsa -out private_key.pem 2048
    openssl rsa -in private_key.pem -pubout -out public_key.pem

  2. In your Epic app registration, navigate to the Public Keys section and upload or paste the contents of public_key.pem as a JWK or PEM. Epic will use this public key to verify JWTs your application signs.

  3. Keep private_key.pem secure. This is the Private Key (PEM) you will enter in Nexla. Do not share it or commit it to version control.

Epic requires the JWT exp claim to be no more than 5 minutes in the future. Nexla automatically manages JWT generation and timing within this constraint. The key algorithm used is RS384.

Identify Your FHIR Base URL​

Each Epic organization exposes its own FHIR R4 base URL. The default sandbox endpoint is:

https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4

For a production Epic customer environment, the base URL typically follows the pattern:

https://<organization>.epic.com/interconnect-fhir-oauth/api/FHIR/R4

Contact the Epic customer's integration team or refer to their SMART configuration endpoint (/.well-known/smart-configuration) to confirm the correct base URL for their organization.

Additional documentation for Epic's backend OAuth 2.0 flow is available at fhir.epic.com/Documentation?docId=oauth2.

Create an EPIC EHR Credential​

  • To create a new EPIC EHR credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

EPIC Backend OAuth2 (JWT) Settings​

This credential uses Epic's Backend Services OAuth 2.0 flow, where your application authenticates by presenting a signed JWT to obtain a short-lived access token. No user interaction is required, making it well-suited for automated, system-to-system data pipelines.

  1. Enter the Epic FHIR R4 base URL for the target organization in the FHIR Base URL field. This URL identifies both the API root and the OAuth 2.0 token endpoint used for authentication.

    • Sandbox/testing: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
    • Production: Use the base URL provided by the Epic customer's integration team.

  2. Enter the Client ID obtained from your Epic app registration in the Client ID field. This value uniquely identifies your application to Epic's authorization server and corresponds to the OAuth 2.0 client_id.

    Epic issues separate Client IDs for non-production (sandbox) and production environments. Ensure you use the correct Client ID for the environment you are connecting to.

  3. Paste the RSA private key in PEM format into the Private Key (PEM) field. This is the private key that corresponds to the public key you registered in your Epic app record. Nexla uses this key to sign the JWT assertions submitted to Epic's token endpoint (RS384 algorithm).

    Important

    The private key grants access to any Epic data your app is authorized for. Store it securely and restrict access to authorized personnel only. Do not paste a key that is shared across other systems.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.