Written and maintained by CASRAI Editorial Board
Last updated
Epic on FHIR (hosted at fhir.epic.com as part of the open.epic interoperability portal) is Epic Systems’ standards-based API platform and developer portal for integrating external software applications, patient apps, and clinical research pipelines with Epic Electronic Health Record (EHR) environments. Built on the HL7 FHIR (Fast Healthcare Interoperability Resources) standard and served through Epic’s Interconnect web services gateway, Epic on FHIR provides RESTful endpoints for reading and writing structured clinical, administrative, and scheduling data.
For clinical research informatics teams, biomedical software engineers, and health system integration architects, building against Epic on FHIR requires understanding how Epic structures its FHIR version paths (`R4`, `STU3`, and `DSTU2`), how US Core profiles govern resource search parameters, how interactive SMART on FHIR launches differ from autonomous Backend Services OAuth 2.0 JWT authentication, and how clinical apps progress from the public sandbox to hospital production directories or Epic Showroom.
What Is Epic on FHIR and How Does Interconnect Serve FHIR APIs?
Inside an Epic health system environment, core clinical transactions reside in the high-performance hierarchical Chronicles database (`M` / Caché / IRIS). External applications never query Chronicles directly over the network. Instead, external HTTPS requests terminate at Epic Interconnect, the enterprise API gateway that validates OAuth 2.0 bearer tokens, enforces client access control lists (ACLs) and rate limits, translates RESTful FHIR queries into internal Chronicles database calls, and returns JSON or XML FHIR payloads.
Epic’s FHIR endpoint URLs follow a standardized path convention per health system environment (`…/api/FHIR/R4/`, `…/api/FHIR/STU3/`, or `…/api/FHIR/DSTU2/`):
- HL7 FHIR Release 4 (`R4`, v4.0.1): The primary normative release required by the ONC 21st Century Cures Act § 170.315(g)(10) Standardized API for Patient and Population Services certification criterion. All new clinical research integrations, Electronic Data Capture (EDC) eSource connectors, and patient-facing apps should target `R4`.
- HL7 US Core Implementation Guide Conformance: Epic’s `R4` endpoints implement the HL7 US Core profiles mapping to United States Core Data for Interoperability (USCDI) data classes—including `Patient`, `Encounter`, `Condition`, `Observation` (vital signs, laboratory results, smoking status), `MedicationRequest`, `AllergyIntolerance`, `Immunization`, `Procedure`, `DiagnosticReport`, `DocumentReference`, and `Provenance`.
- CapabilityStatement Discovery (`/metadata`): Every Epic FHIR base URL exposes an unauthenticated `GET [base]/metadata` endpoint returning a FHIR `CapabilityStatement` resource alongside `GET [base]/.well-known/smart-configuration`, allowing clients to dynamically discover supported resources, search parameters, and OAuth 2.0 `/authorize` and `/token` URLs.
Authentication Models: SMART on FHIR App Launch vs. Backend OAuth 2.0 JWT
Epic on FHIR enforces different OAuth 2.0 security flows depending on whether an application runs interactively in front of a human user (a clinician or a patient) or operates autonomously as a background server daemon:
| Integration Pattern | OAuth 2.0 Grant & Standard | Identity & Context Claims | Primary Healthcare & Research Use Cases |
|---|---|---|---|
| Clinician EHR Launch (Hyperspace / Hyperdrive) | SMART App Launch (Authorization Code Grant + PKCE + OpenID Connect) | launch token yields patient, encounter, and fhirUser (Practitioner) context. |
Bedside clinical decision support (CDS), trial eligibility screening widgets, and point-of-care eSource data capture. |
| Patient Standalone Launch (MyChart) | SMART Standalone Launch (Authorization Code Grant + PKCE) | Patient authenticates via MyChart credentials; token returns authorized patient ID and patient/*.read scopes. |
Patient-mediated clinical trial recruitment, ePRO mobile apps, and longitudinal personal health record synchronization. |
| Backend Services (System-to-System Daemon) | OAuth 2.0 Client Credentials Grant with signed JWT assertion (urn:ietf:params:oauth:client-assertion-type:jwt-bearer) |
No interactive user; signed RSA JWT (`iss`, `sub`, `aud`, `jti`, `exp`) verified against registered public key / JWKS URL; uses system/* scopes. |
Automated clinical registry synchronization, nightly research warehouse ETL, and FHIR Bulk Data ($export) cohort extraction. |
Anatomy of an Epic Backend OAuth 2.0 JWT Assertion
When a clinical research server or backend pipeline connects to Epic without a human login, it cannot use a static client secret in standard FHIR `R4` backend flows. Instead, during registration on `fhir.epic.com`, the developer uploads an `X.509` public certificate (or registers a JSON Web Key Set [JWKS] URL) and receives both a Non-Production and a Production Client ID. To request an access token, the backend service generates a JSON Web Token (JWT) signed with its private RSA key (`RS384` or `RS256`) containing five mandatory claims:
- `iss` (Issuer): The application’s Epic Client ID (Non-Production ID for sandbox/TST environments; Production ID for PRD).
- `sub` (Subject): Must match the `iss` Client ID.
- `aud` (Audience): The exact full URL of the target health system’s Epic Interconnect OAuth 2.0 token endpoint (e.g., `https://…/interconnect-fhir-oauth/oauth2/token`).
- `jti` (JWT ID): A cryptographically random unique identifier (max 151 characters) generated per token request to prevent replay attacks.
- `exp` (Expiration Time): A Unix epoch timestamp no more than 5 minutes in the future (alongside `nbf` and `iat`).
The client sends this signed JWT via an `application/x-www-form-urlencoded` `POST` request to the `/oauth2/token` endpoint with `grant_type=client_credentials`. Upon signature verification, Epic Interconnect returns a time-limited Bearer access token valid for the configured `system/*.read` or `system/*.write` scopes.
Core FHIR R4 Resources for Clinical Research and eSource Workflows
While multi-institutional de-identified observational research across Epic health systems often uses the centralized Epic Cosmos research platform, site-level clinical trials and prospective registries rely on Epic on FHIR APIs to automate EHR-to-EDC (eSource) data transfer and study recruitment:
- Demographics and Visit Tracking (`Patient` & `Encounter`): Retrieving MRN identifiers, birth dates, race/ethnicity OMB extensions, and inpatient/ambulatory admission dates to populate study screening logs.
- Laboratory and Vital Sign Measurements (`Observation`): Querying `Observation?patient=&category=laboratory` (coded in LOINC with UCUM units) and `category=vital-signs` to flow safety labs and blood pressure readings directly into electronic Case Report Forms (eCRFs) without manual transcription error.
- Diagnoses and Concomitant Medications (`Condition` & `MedicationRequest`): Screening inclusion/exclusion criteria against ICD-10-CM/SNOMED CT problem list entries and RxNorm active medication orders.
- Unstructured Clinical Notes (`DocumentReference` & `DiagnosticReport`): Fetching progress notes, discharge summaries, and pathology/radiology narratives for natural language processing (NLP) phenotyping or adverse event adjudication.
- Population-Level Bulk Data (`Group/$export`): Executing asynchronous FHIR Bulk Data Export requests that return newline-delimited JSON (`.ndjson`) files for an enrolled research study cohort defined in an Epic `Group` or Registry list.
Sandbox Testing, Endpoint Discovery, and Production Deployment
Developing against `fhir.epic.com` follows a structured progression from sandbox validation to health system activation:
- App Registration and Sandbox Testing: Developers register an application on `fhir.epic.com`, select the exact FHIR `R4` resources and SMART scopes required, and test against Epic’s public sandbox test patients (such as Camila Lopez or Derrick Lin) using the built-in Launcher and API Try-It tools.
- Patient-Facing Auto-Download vs. Clinician/Backend Activation: Under ONC Cures Act rules, patient-facing read-only apps that conform strictly to US Core `R4` profiles are automatically synchronized to participating Epic health systems’ production endpoint lists via Epic’s published `Endpoints` R4 Bundle. By contrast, clinician-facing EHR-launch apps, write-capable apps, and Backend Services daemons require explicit security review, client ID activation, and scope mapping by each hospital’s local Epic Bridges/Interconnect administrator.
Frequently Asked Questions
What is Epic on FHIR?
Epic on FHIR (accessible via fhir.epic.com and open.epic) is Epic Systems’ standards-based developer ecosystem and RESTful API platform that exposes Electronic Health Record (EHR) data using HL7 Fast Healthcare Interoperability Resources (FHIR), SMART on FHIR authorization, and US Core profiles through Epic’s Interconnect gateway.
Which HL7 FHIR versions and profiles does Epic support?
While Epic’s Interconnect gateway maintains backward-compatible endpoints for legacy DSTU2 and STU3 integrations, HL7 FHIR Release 4 (R4, v4.0.1) constrained by the HL7 US Core Implementation Guide is the primary production standard used to satisfy ONC 21st Century Cures Act 170.315(g)(10) interoperability mandates.
How do backend clinical research pipelines authenticate to Epic FHIR APIs without a user login?
System-to-system services and automated research data pipelines use SMART Backend Services OAuth 2.0 (Client Credentials Grant with a signed RS384/RS256 JSON Web Token assertion). The client constructs a short-lived JWT containing iss and sub set to the Epic Client ID, aud set to the hospital’s Interconnect /oauth2/token URL, and a unique jti nonce, signs it with its private RSA key, and exchanges it for a bearer access token.
