Create an Epic Developer Account

If you don't already have one, create a developer account at fhir.epic.com.

• Sign up using your organization's email domain (e.g., someone@your-company.com)
• Your organization will own this account and all apps created under it
• Keep your login credentials secure

Create a New Application in fhir.epic.com Developer Portal

In fhir.epic.com Developer Portal, create a new application and choose the app type that matches your workflow:

1. Click Create App in your fhir.epic.com dashboard
2. Choose your application type:
   • For Standalone (patient-facing): Select Patient-Facing App or Clinician-Facing App (3-legged OAuth)
   • For Backend (B2B): Select Backend System App (client_credentials with JWT assertion — no Basic Auth option)
   • For Embed Launch (in-EHR): Select EHR App (SMART on FHIR)
3. Enter an app name and description (e.g., "ConnectHealth Integration - Sandbox")
4. Complete the required fields and click Submit

Retrieve Your Client ID and Configure Credentials

After creating your app, copy your Client ID and configure the required credential fields:

1. Open your app in fhir.epic.com Developer Portal and copy the Client ID (a UUID format string — Epic does not issue a Client Secret for B2B apps)
2. For Standalone and Embed Launch: Register the Redirect URI (OAuth callback URL) from ConnectHealth: https://your-connecthealth-domain/api/workflow/auth/{integrationId}/callback
   You will get the exact {integrationId} from ConnectHealth after creating your connection
3. For Embed Launch: Also register the Launch URL: https://your-connecthealth-domain/api/workflow/auth/{integrationId}/launch
4. For B2B (Backend): Copy the JWKS URI from your ConnectHealth connection settings and paste it into your app's JWKS URI field in fhir.epic.com Developer Portal. This is how Epic verifies your JWT assertions without sharing private keys
5. Click Save

Submit for Sandbox Approval

Applications created on fhir.epic.com for sandbox testing are generally available immediately in the public sandbox. However, testing in a hospital's specific environment requires additional steps:

• Your public sandbox app is typically auto-approved for use against fhir.epic.com endpoints
• Moving the app into a specific hospital's non-production or production environment requires their Epic TS (Technical Server) administrator to explicitly approve and install your app's Client ID via their Connection Hub
• Once the Client ID is active, you can begin using it in ConnectHealth

Configure in ConnectHealth

Now you're ready to configure your Epic connection in ConnectHealth:

1. In ConnectHealth, navigate to Connections and create a new connection
2. Select Epic as the EHR type
3. Select your workflow type:
   • Standalone for patient-facing applications
   • Backend for server-to-server automation
   • Embed Launch for in-EHR applications
4. Paste your Client ID from fhir.epic.com Developer Portal
5. Fill in the FHIR Base URL (ConnectHealth auto-discovers auth and token endpoints from it)
6. For B2B: ConnectHealth auto-generates an RSA key pair — copy the JWKS URI shown in your connection settings and register it in fhir.epic.com Developer Portal (if not done already in Step 3)
7. Save your connection

Test with Sandbox Data

Test your integration using Epic's sandbox (see Sandbox Environment Setup below for test data and URLs).

• For Standalone: Initiate OAuth and log in using the Epic MyChart sandbox credentials (fhircamila / epicepic1)
• For Backend: Request a system token and test FHIR calls against the sandbox FHIR base URL
• Verify that data flows correctly between Epic and ConnectHealth

Production App (When Ready)

When you're ready to go to production:

1. Create a new production application in fhir.epic.com Developer Portal targeting the Production environment
2. Configure it with the same settings as your sandbox app (Redirect URI, JWKS URI, scopes, etc.)
3. Submit for Epic's production review (this may take days to weeks)
4. Coordinate with your customer's Epic administrator to activate your app on their Epic instance
5. Once both approvals are in place, create a new production connection in ConnectHealth using your production Client ID and the customer's Epic FHIR base URL
6. See the Epic FHIR Documentation for detailed production submission guidance

Log in to the ConnectHealth Dashboard

Open your ConnectHealth instance (the URL where your deployment is hosted) and sign in with your account credentials.

Navigate to Settings → API Keys

From the left navigation, click Settings, then open the API Keys tab. If you have never generated a key before, the list will be empty.

Create a New API Key

Click Create API Key, enter a descriptive name (e.g., epic-prod-client or embed-launch-dev), and submit. Use one key per environment or per client application so you can rotate individual keys without affecting others.

Copy Your API Key

ConnectHealth automatically saves your API key securely. You can view and copy the key value from Settings → API Keys at any time. Click your key name to reveal and copy it whenever you need it.

Use the Key in the x-api-key Header

Pass the key on every request to a protected endpoint using the header name x-api-key (lowercase, hyphenated). Example:

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

Endpoints requiring this header are listed in the API Endpoints section below.