> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/epic.md).

# Epic (on FHIR)

## OAuth app properties

| Property                | Value                                                                                                                                                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Multi-tenant**        | **Conditional.** One client ID can be used at any Epic organization, but only after that organization downloads and activates it. Apps for clinicians are not distributed automatically.                                      |
| **Vendor review**       | **Required** by each Epic organization: it signs the open.epic API Subscription Agreement, runs its own security review and downloads the client record. Epic itself does not review the app; a Showroom listing is optional. |
| **Review time**         | Set by each organization. Not published.                                                                                                                                                                                      |
| **Users before review** | Sandbox test users only. No real users until an organization activates the app.                                                                                                                                               |
| **App owner**           | An Epic on FHIR (fhir.epic.com) developer account.                                                                                                                                                                            |
| **Regions**             | Per Epic organization. Each one hosts its own FHIR and OAuth endpoints.                                                                                                                                                       |
| **Client secret**       | No expiry documented. Epic recommends a different secret for each organization and each environment (non-production, production).                                                                                             |
| **Rate limits**         | Not published.                                                                                                                                                                                                                |
| **Checked**             | 2026-11-13                                                                                                                                                                                                                    |

**Limitations**

* The connector configuration holds one FHIR base URL, so one Appmixer configuration connects to one Epic organization.
* After you mark the app **Ready for Production**, neither you nor Epic can change it, except for adding redirect URIs and changing JWK Set URLs. Other changes, such as new Incoming APIs, need a new app.
* Epic issues refresh tokens only to a confidential client. Without a client secret, users connect the account again when the access token expires.
* Incoming APIs added later apply only after users connect their accounts again.

Sources: [Epic on FHIR documentation: app creation and request process, OAuth 2.0](https://fhir.epic.com/Documentation?docId=oauth2), [open.epic](https://open.epic.com). What the rows mean: [OAuth app properties](https://docs.appmixer.com/connector-configuration/oauth-app-properties.md).

### 1. Create an Epic on FHIR account

Sign up at <https://fhir.epic.com> and log in to the developer portal.

### 2. Register an app

Go to **Build Apps** → **Create** and fill in:

* **Application Name**: anything you want.
* **Application Audience**: `Clinicians or Administrative Users` (the connector uses `user/*.read` SMART scopes).
* **SMART on FHIR Version**: `R4`.
* **Redirect URI**: depends on your environment, usually in the following format: `https://api.qa.appmixer.com/auth/epic/callback`

### 3. Select Incoming APIs

This is the most important step. Epic authorizes each FHIR interaction separately — for every resource there is a `.Read` **and** a `.Search` API, often split further by use-case category. If a `.Search` API is missing, the corresponding connector component fails with `403 insufficient_scope` even though authentication succeeds.

Select **all `(R4)` variants** (ignore DSTU2 and STU3) of both `.Read` and `.Search` for the resources below. The table shows which connector component depends on which API:

| Connector component                                                      | Required Incoming APIs (R4)                                                                                                                          |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| GetAppointment, NewAppointment, UpdatedAppointment, CancelledAppointment | `Appointment.Read`, `Appointment.Search` — select all R4 variants                                                                                    |
| FindPatients, GetPatient                                                 | `Patient.Read`, `Patient.Search`                                                                                                                     |
| FindConditions                                                           | `Condition.Read (Problems)`, `Condition.Search (Problems)` — select all other `Condition.*` R4 variants too (Encounter Diagnosis, Health Concern, …) |
| FindVitalSigns                                                           | `Observation.Read (Vitals)`, `Observation.Search (Vitals)`                                                                                           |
| FindLabResults                                                           | `Observation.Read (Labs)`, `Observation.Search (Labs)`                                                                                               |
| FindSmokingHistory                                                       | `Observation.Read (Social History)`, `Observation.Search (Social History)` (a.k.a. Smoking History)                                                  |
| GetMedication                                                            | `Medication.Read`                                                                                                                                    |
| FindMedicationRequests, GetMedicationRequest                             | `MedicationRequest.Read (Orders)`, `MedicationRequest.Search (Orders)` — select all `MedicationRequest.*` R4 variants                                |
| FindProcedures, GetProcedure                                             | `Procedure.Read`, `Procedure.Search` — select all R4 variants (Surgeries, Orders, …)                                                                 |
| FindCarePlans                                                            | `CarePlan.Read (Longitudinal)`, `CarePlan.Search (Longitudinal)`                                                                                     |
| FindGoals                                                                | `Goal.Read (Patient)`, `Goal.Search (Patient)`                                                                                                       |
| FindImmunizations                                                        | `Immunization.Read`, `Immunization.Search`                                                                                                           |
| FindDiagnosticReports, GetDiagnosticReport                               | `DiagnosticReport.Read (Results)`, `DiagnosticReport.Search (Results)`                                                                               |
| FindDocumentReferences                                                   | `DocumentReference.Read (Clinical Notes)`, `DocumentReference.Search (Clinical Notes)`                                                               |
| FindDevices                                                              | `Device.Read (Implants)`, `Device.Search (Implants)`                                                                                                 |
| MakeApiCall                                                              | whatever APIs the called endpoint requires — the component sends arbitrary authorized FHIR requests                                                  |

The exact labels can differ slightly between Epic portal versions — when in doubt, select every `(R4)` variant of the resource.

#### Alphabetical checklist

The Epic UI lists available APIs alphabetically. Work through this list top to bottom (all items are the `(R4)` variants):

```
Appointment.Read (Appointments) (R4)
Appointment.Read (Prior Auth) (R4)
Appointment.Search (Appointments) (R4)
Appointment.Search (Prior Auth) (R4)
CarePlan.Read (Longitudinal) (R4)
CarePlan.Search (Longitudinal) (R4)
Condition.Read (Problems) (R4)
Condition.Search (Problems) (R4)
Device.Read (Implants) (R4)
Device.Search (Implants) (R4)
DiagnosticReport.Read (Results) (R4)
DiagnosticReport.Search (Results) (R4)
DocumentReference.Read (Clinical Notes) (R4)
DocumentReference.Search (Clinical Notes) (R4)
Goal.Read (Patient) (R4)
Goal.Search (Patient) (R4)
Immunization.Read (R4)
Immunization.Search (R4)
Medication.Read (R4)
MedicationRequest.Read (Orders) (R4)
MedicationRequest.Search (Orders) (R4)
Observation.Read (Labs) (R4)
Observation.Read (Social History) (R4)
Observation.Read (Vitals) (R4)
Observation.Search (Labs) (R4)
Observation.Search (Social History) (R4)
Observation.Search (Vitals) (R4)
Patient.Read (R4)
Patient.Search (R4)
Procedure.Read (Orders) (R4)
Procedure.Read (Surgeries) (R4)
Procedure.Search (Orders) (R4)
Procedure.Search (Surgeries) (R4)
```

If a label from the list does not exist exactly (e.g. `Observation.Search (Smoking History) (R4)` instead of `Social History`), pick the closest `(R4)` variant of the same resource and interaction.

{% hint style="info" %}
The connector requests these SMART on FHIR scopes during authentication: `openid`, `fhirUser` and `user/<Resource>.read` for Patient, Condition, Observation, Medication, MedicationRequest, Procedure, CarePlan, Goal, Immunization, DiagnosticReport, DocumentReference, Device and Appointment. The `.read` scope covers both the read and search interaction — whether a search call is actually allowed is controlled purely by the Incoming APIs selected above, not by the scope string. No connector configuration change is needed when you add more APIs to the app.
{% endhint %}

### 4. Client ID and client secret

After saving the app, Epic shows a **Non-Production Client ID** and a **Production Client ID**. Use the non-production ID against the Epic sandbox (`https://fhir.epic.com/interconnect-fhir-oauth`).

{% hint style="warning" %}
Changes on fhir.epic.com — creating an app, generating a client secret, adding Incoming APIs — are **not effective immediately**. Propagation to the sandbox typically takes tens of minutes and can take up to 12 hours. Until then the token endpoint returns `invalid_client` (unknown app / secret) or searches return `403 insufficient_scope` (missing APIs).

Additionally, Epic freezes the granted permissions at authorization time. After adding Incoming APIs to an existing app, **users must re-authenticate** — refreshing the access token is not enough, existing tokens (including refreshed ones) keep returning `403 insufficient_scope`.
{% endhint %}

If you generate a client secret, Epic requires HTTP Basic authentication at the token endpoint (the connector handles this automatically). Without a secret the app acts as a public client — this works in the sandbox, but Epic may not issue a refresh token, so users must re-authenticate when the access token expires (1 hour).

Set the client ID and client secret in the Backoffice; see [Backoffice configuration](#backoffice-configuration).

### Going to production

The public sandbox (`fhir.epic.com`) is only for development. Real patient data lives in the Epic instances of individual healthcare organisations — there is no central production API. Going live means:

1. **Mark the app "Ready for Production"** on fhir.epic.com. This activates the **Production Client ID** (so far you have been using the non-production one).
2. **Get activated by each healthcare organisation.** For apps with the `Clinicians or Administrative Users` audience (this connector — `user/*.read` scopes) the gatekeeper is the Epic customer, not Epic itself. Each organisation typically requires a business agreement and a **HIPAA Business Associate Agreement (BAA)**, runs its own security & privacy review, and then activates your Production Client ID in their Epic environment, including the list of allowed APIs (their counterpart of your Incoming APIs selection). Epic's paid **Vendor Services** program (successor of App Orchard) and the Connection Hub/Showroom listing make this process smoother when distributing to multiple customers, but do not replace per-organisation activation.
3. **Point the connector at the organisation's endpoints.** Every Epic customer hosts its own FHIR and OAuth endpoints (see the public endpoint directory on [open.epic.com](https://open.epic.com)). Set `clientId` and `clientSecret` to the Production Client ID (and secret, if issued) and `epicFhirBaseUrl` (and, if needed, `epicOauthBaseUrl`) to the organisation's endpoints; see [Backoffice configuration](#backoffice-configuration).
4. **Users authenticate with their clinical (EHR) credentials** of that organisation. What they can see in patient charts is governed by their Epic user role and the APIs the organisation enabled — the connector never grants more access than the organisation allows. Existing accounts must re-authenticate after any endpoint or app change.
5. **Compliance.** Once real PHI flows through Appmixer, the deployment itself must satisfy HIPAA requirements (BAA between you and the customer, encryption, audit logging, data retention). Plan this on the deployment side; no connector change is involved.

A practical rollout path: pilot with one partner organisation against their **non-production environment** first (every Epic customer has TST/POC instances — an intermediate step between the public sandbox and production), then request production activation.

### Sandbox test logins

Epic provides test users for the sandbox, e.g. provider login `FHIR` / `EpicFhir11!`. Test patient: Camila Lopez (`erXuFYUfucBZaryVksYEcMg3`). See <https://fhir.epic.com/Documentation?docId=testpatients> for the full list.

## Backoffice configuration

Configuration ID: `appmixer:epic` (Backoffice → Configuration; see [Connector Configuration](https://docs.appmixer.com/getting-started/services) for how a configuration is created and how its keys reach the connector).

* `clientId` — Client ID of the Epic app registered above: the Non-Production Client ID for the sandbox, the Production Client ID for a live organisation. Not needed when Epic is authenticated through the Appmixer Auth Hub.
* `clientSecret` — Optional. Client secret of the same app, if you generated one. Without it the app is a public client and Epic may not issue refresh tokens. Not needed with the Auth Hub.
* `epicFhirBaseUrl` — Optional. FHIR R4 base URL of the Epic organisation, e.g. `https://ehr.hospital.org/interconnect-prd/api/FHIR/R4`. Default `https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4` (the public sandbox). One configuration connects to one organisation.
* `epicOauthBaseUrl` — Optional. OAuth base URL of the organisation. When not set, the connector derives it from `epicFhirBaseUrl` using Epic's standard interconnect layout (`…/api/FHIR/R4` → `…/oauth2`); for the sandbox it is `https://fhir.epic.com/interconnect-fhir-oauth/oauth2`. Set it only when the organisation uses a non-standard layout.
* `outputFilePrefix` — Optional. File name prefix of the CSV file that **FindPatients** creates when its output is set to a file; the file is named `<prefix>-<component name>.csv`. Default `epic-objects-export`.

The same keys can be set with the CLI (`-u` updates the existing configuration instead of creating it):

```bash
appmixer service-config set appmixer:epic -u -d '{
  "clientId": "<client id>",
  "clientSecret": "<client secret>",
  "epicFhirBaseUrl": "<FHIR R4 base URL>"
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/epic.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
