Epic App Orchard Approval: What Engineers Actually Experience

What Is Epic App Orchard?

Epic App Orchard is Epic's official marketplace for third-party applications that integrate with Epic EHR via FHIR R4 APIs. Any custom application that needs to launch from within Epic's Hyperspace interface — or that needs bi-directional data access to Epic-managed patient records — must go through the App Orchard review and approval process.

This is not optional. Hospitals running Epic will not grant production API access to unapproved applications, regardless of how mature your engineering is.

The Four Stages of App Orchard Approval

Stage 1: Application Registration (Week 1–2)

You begin by creating an account in the Epic on FHIR developer portal and registering your application. At this stage you define:

• Your application type (Patient-facing vs. Clinician-facing vs. Backend)
• The FHIR resources your app needs (Patient, Appointment, Observation, etc.)
• Your OAuth 2.0 redirect URIs

Epic issues you a Non-Production Client ID that works against their public sandbox environment (open.epic.com). This sandbox has synthetic patient data and does not require hospital-specific approval.

Stage 2: Sandbox Development (Week 2–12)

This is where most teams spend the majority of their time. The open.epic.com sandbox is useful for testing the authentication flow, but it's deliberately limited — it doesn't have the custom extensions or specific FHIR profiles that each hospital's Epic instance uses.

Common blockers at this stage:

• SMART on FHIR launch context: Clinician-facing apps that launch from Hyperspace require a very specific launch flow. See the Epic EHR FHIR integration challenges guide for a detailed walkthrough.
• Token refresh handling: Access tokens from Epic expire in 8 hours. Your application must handle silent token refresh without dropping the user session.
• Scope negotiation: Epic's sandbox may not have your requested scopes enabled by default. You need to contact Epic support to enable them.

// Handling Epic's token expiration silently
const ensureFreshToken = async (client) => {
    const { token_at, expires_in } = client.state.tokenResponse;
    const expiresAt = token_at + (expires_in * 1000);
    if (Date.now() > expiresAt - 60000) {
        await client.refresh(); // refresh 60s before expiry
    }
};

Stage 3: Customer-Specific Integration (Week 8–24)

Once sandbox development is complete, the real complexity begins: getting your specific hospital client to open their Epic instance to your application.

Each hospital's Epic instance is configured independently. The hospital's Epic team must:

1. Create a new "App Record" in their local Epic system
2. Assign your Non-Production Client ID to that App Record
3. Grant your requested FHIR scopes
4. Test in their internal non-production Epic environment

This is the stage that takes longest — not for engineering reasons, but because hospital IT departments operate on their own change management calendars. Four to eight weeks is typical. It can stretch to six months.

Stage 4: Production Approval (Variable)

Once hospital testing passes, the App Record is promoted to production. At this point your application is live against real patient data. Epic may also require a formal App Orchard listing if you plan to distribute to multiple Epic customers.

What Actually Fails Apps

In practice, the most common failure points are:

1. Missing FHIR profile extensions: Your standard FHIR Patient resource is missing a mandatory Epic-specific extension field. The Epic validator rejects it — sometimes silently.
2. Mismatched redirect URI: The launch URL and redirect URI don't match exactly, including trailing slashes.
3. Scope over-requesting: Requesting more FHIR scopes than your application actually uses is a red flag during App Orchard review.
4. Missing offline_access scope: If your application processes data in the background after the user closes the browser, you need offline_access — many teams forget to request it.

Any application that reaches production must also satisfy HIPAA technical safeguards — encrypted transport, audit logging, and scoped IAM — before Epic's security review will pass.

The Multi-EHR Reality

For clinic groups that use more than one EHR (some practices on Epic, others on Cerner or Athena), building a separate SMART on FHIR integration for each vendor is not sustainable. A middleware translation layer abstracts the vendor-specific complexity — your application talks to one internal API, and the middleware handles Epic, Cerner, and Athena behind the scenes.

If you're still working with legacy HL7 v2 feeds alongside FHIR, the HL7 v2 → FHIR R4 migration guide covers the full pipeline. See also the Epic ↔ Cerner integration reference architecture for a concrete example of how the middleware layer is structured across two EHR environments.

The EHR / EMR Middleware service handles App Orchard navigation and multi-EHR integration for expanding clinic networks.