Create a developer account at fhir.epic.com and log in to the developer portal to access the 'My Apps' section.
Create a new app record: specify the application name, application type (patient-facing vs. clinician-facing vs. backend), SMART launch type (standalone, EHR, or backend services), and redirect URI.
For sandbox testing, select the Epic on FHIR sandbox environment; Epic provides synthetic patient data (e.g., the open.epic.com sandbox) accessible without a production agreement.
Configure OAuth scopes in the app record; Epic uses a proprietary scope approval workflow where each scope must be individually enabled; check the Epic FHIR API documentation for scope availability by resource.
Obtain your client_id from the app record; use this in SMART launch flows against the sandbox base URL (e.g., https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4).
For production access, submit the app for Epic review via the developer portal and coordinate with the target health system's Epic administrator to activate the app in their instance.
Known gotchas
Epic's sandbox client_id differs from production client_ids issued by individual health systems; a sandbox app does not automatically work against any production Epic instance.
Epic enforces scope limitations by resource type and user role; scopes available in the sandbox may not be available in all production Epic instances without explicit health-system-level activation.
Epic uses non-standard extensions (e.g., Epic-specific resource IDs and identifier systems); review Epic's resource documentation alongside standard FHIR R4 to handle Epic-specific patterns.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp