Written and maintained by CASRAI Editorial Board
Last updated
The Epic FHIR sandbox—hosted publicly at open.epic.com—is Epic Systems Corporation’s free, non-production developer environment for building, authenticating, and testing third-party applications against Epic on FHIR RESTful APIs (HL7 FHIR R4 and DSTU2/STU3) before deploying to live health system environments. Whether engineering a patient-facing mobile clinical trial ePRO app, a clinician-facing SMART on FHIR clinical decision support dashboard embedded inside Epic Hyperspace, or a backend system-to-system eSource synchronization service, developers use the Open.Epic sandbox to register OAuth 2.0 client credentials, configure JSON Web Key Sets (JWKS), and execute real HTTP requests against pre-populated synthetic patient records.
How Do You Register and Test an App in the Epic FHIR Sandbox?
Unlike commercial partner tiers inside Epic Showroom and Epic Vendor Services that require annual membership agreements, anyone can create a free developer account at open.epic.com and provision a sandbox application by following a five-step technical workflow:
- Create an Open.Epic Developer Account and Application: Sign in at
open.epic.com, navigate to Build Apps, and create a new application entry. Select the target audience category: Patients (standalone MyChart OAuth 2.0 launch), Clinicians or Administrative Users (EHR Launch inside Hyperspace/Hyperdrive or standalone clinician launch), or Backend Systems (headless service-to-service OAuth 2.0 using asymmetric JWT client assertions). - Select Incoming FHIR R4 APIs and US Core Scopes: Choose the exact FHIR resources and interactions your application requires—for example,
Patient.Read,Observation.Search (Vital Signs / Laboratory),Condition.Read,MedicationRequest.Search, orDocumentReference.Create. Follow the principle of least privilege: hospital security teams review requested scopes during production onboarding and reject apps requesting broad read/write scopes unneeded by their clinical workflow. - Configure Redirect URIs and Asymmetric Public Keys (JWKS): For interactive SMART launches, register one or more exact HTTPS
redirect_uricallback endpoints (e.g.,https://localhost:3000/callbackfor local development or Postman’s OAuth callback URL). For Backend Systems or asymmetric confidential clients, upload an X.509 public certificate or provide a hosted JSON Web Key Set (JWKS) URL (signed with RS384/RS256). - Retrieve Non-Production vs. Production Client IDs: Upon saving the app configuration, Open.Epic generates two distinct identifiers: a Non-Production Client ID (specifically for testing against the Open.Epic sandbox and hospital non-production `TST`/`SUP` environments) and a Production Client ID. Important operational rule: After registering or modifying an app’s API list or public keys on
open.epic.com, allow 30 to 60 minutes for key and client-ID propagation to the sandbox OAuth server before executing token requests. - Execute Sandbox Queries Against the Base FHIR R4 Endpoint: Point your HTTP client, Postman collection, or HAPI FHIR client to the Open.Epic FHIR R4 base URL:
https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
Synthetic Sandbox Test Patients for Postman and Automated Testing
Because the Open.Epic sandbox enforces realistic patient-matching and authorization scopes, developers cannot query arbitrary integer IDs. Epic pre-populates the sandbox with standardized synthetic patient personas (using encrypted logical FHIR IDs) and MyChart test credentials:
| Synthetic Test Persona | Sandbox FHIR R4 Logical ID | Demographics (DOB / Sex) | Primary Sandbox Testing Role |
|---|---|---|---|
| Camila Lopez | erXuFYUfucBZaryVksYEcMg3 |
1987-09-12 / Female |
Standard patient-facing SMART Standalone Launch test persona (MyChart sandbox login: fhircamila / password: epicepic1) |
| Derrick Lin | eq081-VQEgP8drUUqCWzHfw3 |
1973-06-03 / Male |
Rich longitudinal inpatient/outpatient clinical data (conditions, labs, vitals, medications) for US Core search testing |
| Jason Argonaut | eIXesllypH3M9tAA5WdJftQ3 |
1985-08-15 / Male |
HL7 Argonaut Project reference persona for testing allergy, immunization, and problem-list conformance |
How Does SMART on FHIR Authentication Work in Epic?
All requests to the Epic FHIR sandbox require an OAuth 2.0 Bearer access token obtained from Epic’s authorization server. You discover the exact authorization and token endpoints dynamically by querying the server’s SMART configuration document at:
GET https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/.well-known/smart-configuration
Epic supports three primary OAuth 2.0 / SMART App Launch authentication flows in the sandbox:
- 1. SMART Standalone Launch (Patient or Clinician): The application redirects the user’s browser to Epic’s
authorizeendpoint withresponse_type=code,client_id=<Non-Prod-Client-ID>,redirect_uri,scope=launch/patient openid fhirUser patient/Patient.read patient/Observation.read,aud=https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4, and PKCE (Proof Key for Code Exchange) parameters (code_challengeandcode_challenge_method=S256). After authenticating (e.g., asfhircamila), Epic redirects back with an authorizationcode, which the app exchanges at thetokenendpoint for anaccess_tokenand the authorizedpatientFHIR ID. - 2. SMART EHR Launch (Clinician In-Context): Launched directly from Epic’s Launchpad test harness inside
open.epic.com(simulating a clinician clicking a button inside an open patient chart in Hyperspace). Epic appends?iss=https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4&launch=<opaque-launch-token>to your app’s launch URL, passing the active patient and encounter context automatically. - 3. Backend Services OAuth 2.0 (RFC 7523
client_credentials): Used for cron jobs, clinical trial eSource pipelines, and population health services with no human user at a browser. The service constructs a signed JSON Web Token (JWT) assertion (withissandsubset to the Non-Production Client ID,audset to the Epic token endpoint,jtiset to a unique nonce, andexp≤ 5 minutes), signs it with the private key matching the registered JWKS public key, and posts it to the token endpoint withgrant_type=client_credentialsandclient_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
How Do You Discover Hospital FHIR R4 Endpoints in Epic Connection Hub?
Once an application passes testing in the Open.Epic sandbox, transitioning to live hospitals requires discovering each health system’s production FHIR R4 base URL and listing the software in Epic Connection Hub (formerly USCDI / endpoint directory integration).
In compliance with the ONC 21st Century Cures Act Final Rule (45 CFR § 170.315(g)(10)), Epic publishes a machine-readable FHIR Bundle containing the live production FHIR R4 base URLs and Organization identifiers for every Epic health system in the United States at:
https://open.epic.com/Endpoints/R4 (for FHIR R4 endpoints) and https://open.epic.com/Endpoints/DSTU2 (for legacy DSTU2).
For patient-facing standalone apps using only ONC-mandated US Core read APIs, once you mark your app as “Ready for Production” in open.epic.com, Epic automatically distributes your Production Client ID across participating Epic customer endpoints worldwide without requiring individual hospital IT build tickets. Conversely, clinician-facing EHR-launch apps, write-back apps, and backend services require each target hospital to enable your app and map security points inside Epic Connection Hub before your Production Client ID is authorized against that hospital’s Interconnect server.
Frequently Asked Questions
How do you register and test an app in the Epic FHIR sandbox?
Register a free developer account at open.epic.com, create an app under Build Apps by selecting your target user class (Patients, Clinicians, or Backend Systems) and required FHIR R4 APIs, configure your redirect URI or JWKS public key, wait 30–60 minutes for your Non-Production Client ID to propagate, and send authenticated requests to https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4 using synthetic test patients like Camila Lopez or Derrick Lin.
How do you discover hospital FHIR R4 endpoints in Epic Connection Hub?
Developers can download the machine-readable FHIR Bundle of all live health system FHIR R4 base URLs directly from https://open.epic.com/Endpoints/R4, while health system IT administrators use Epic Connection Hub to review, configure, and activate third-party clinician and backend applications for their local Epic environment.
How does SMART on FHIR authentication work in Epic?
Epic’s FHIR server discovers authorization and token URLs via .well-known/smart-configuration and supports OAuth 2.0 Authorization Code flow with PKCE for standalone patient/clinician apps, SMART EHR Launch using an opaque launch context token from Hyperspace, and RFC 7523 JWT client-assertion authentication for headless backend services.
