In short
- Patient portal software integrates with Epic as a patient-facing app: patients authenticate with their MyChart credentials through OAuth 2.0 and authorize the specific data types your portal requests through FHIR APIs.
- Epic lets developers build patient-facing FHIR apps without coordinating with a health system, offers automatic client ID distribution to organizations with auto-downloads enabled, and lets customers request other apps through its App Request Process.
- The decisions that shape the project are whether your portal sits beside MyChart or replaces parts of it, which writes you need, and how you keep patients connected with refresh tokens.
Patient portal software integrates with Epic as a patient-facing app. Patients sign in with their MyChart credentials through OAuth 2.0, approve the data your portal asks for, and the portal then reads and writes through the Epic APIs registered to its client ID. The health system's MyChart stays in place, and your portal works beside it.
This guide is for founders, product leads and practice groups who want a portal with their own design and features on top of Epic data. It covers how patients connect, how the app reaches each Epic customer, what the portal can write back, and where these projects usually get stuck. Epic facts come from Epic's developer sites, linked at the end.
How does a patient connect your portal to Epic?
Epic's documentation says patient-facing apps use OAuth 2.0 so that patients can authenticate with their MyChart credentials, and that patients authorize the app to pull specific data types it requests through FHIR APIs. An app can only request data through APIs that are both registered to its client ID and authorized by the patient.
In SMART App Launch terms this is usually a standalone launch. The patient starts in your portal, your portal discovers the Epic organization's authorization endpoints from its FHIR base URL, and the patient is sent to a MyChart sign-in and consent screen. Epic describes standalone launch as the option for apps that use OAuth 2.0 for sign-in but do not need to be launched from Epic.
- The patient picks their health system in your portal.
- Your portal reads that organization's SMART configuration and redirects to its authorization endpoint.
- The patient signs in with MyChart and approves the data types.
- Your portal exchanges the authorization code for an access token, receives the patient's FHIR ID, and starts reading.
The other direction also exists. Epic's remote monitoring material describes patients opening MyChart and launching an app's account-linking page through an embedded launch. That fits products that want an entry point inside MyChart as well as their own.
How does your portal reach each Epic customer?
Every app first registers with Epic and gets a client record with production and non-production client IDs. For patient-facing apps, Epic describes more distribution options than for clinician apps.
- Epic says developers can create patient-facing apps using FHIR without coordination with a health system.
- Client IDs can be distributed automatically to Epic organizations with auto-downloads enabled, for eligible patient-facing apps. Those apps can connect directly to the customer endpoints Epic lists.
- Customers can request an app through the App Request Process.
- Epic also mentions additional options for patient-authorized apps, such as through TEFCA individual access services.
Epic expects the developer to complete and attest to a Data Use Questionnaire for the client ID. Write it as carefully as a privacy policy, because it describes what your portal does with the data patients release.
Automatic distribution only gets your portal connected. If a practice group wants your portal to be the official one for its patients, with its branding, its scheduling rules and its staff answering messages, you still need that customer's agreement and configuration.
What can a portal read from Epic?
EHRs certified to ONC's §170.315(g)(10) criterion must support FHIR R4, US Core and SMART App Launch, with USCDI as the data set. For a portal that means medications, problems, allergies, lab results, vital signs and the rest of USCDI are reachable through standard APIs, subject to the scopes registered and the patient's approval.
Design the portal around what patients come back for. Results, medications and upcoming care are the usual reasons to open a portal. Show the source and date of every value so patients can match it to what they see in MyChart.
Can a portal write back to Epic?
Some writes are available, and each is its own API. Epic's listing includes Create entries such as QuestionnaireResponse (Patient-Entered), Observation (Vital Signs), Patient (Demographics) and DocumentReference (Clinical Notes). Epic also notes that an access token can be used to call FHIR APIs on behalf of the patient.
- Intake forms and questionnaires map to patient-entered QuestionnaireResponse.
- Home readings, such as blood pressure or weight, map to Observation APIs that file to flowsheets.
- Anything that changes scheduling, billing or messaging needs its own API and its own check in Epic's documentation, plus the customer's agreement.
List the writes your portal needs before you design screens. If a feature depends on a write the customer will not enable, you want to find that out during planning, before user testing starts.
How do you keep patients signed in?
A portal that asks patients to sign in to MyChart every visit will lose them. Under §170.315(g)(10), certified EHRs must issue a refresh token valid for at least three months on first connection to confidential apps and native apps that can secure one, and must let the app reconnect without re-authorization while that token is valid.
SMART App Launch issues refresh tokens only when the offline_access or online_access scope is granted. Epic adds that for a patient-facing app using JWTs, Require Refresh Tokens must be checked so you can upload your public key. Build these into the architecture from the start.
- Keep the portal's token handling on your server, not in the browser, so the app can act as a confidential client.
- Store refresh tokens encrypted and tie them to the patient's account in your portal.
- Handle revocation. Certified EHRs must revoke an app's access within one hour of a patient's request, so your portal must notice a revoked token and show the patient how to reconnect.
- Ask for offline access only if a feature needs it, such as background sync of results.
What if a patient is seen at more than one health system?
Each Epic organization is its own connection. It has its own FHIR base URL, its own authorization server and its own MyChart login, and Epic publishes customer endpoints for apps that connect directly. A patient seen at two health systems connects your portal to each one separately and gets a separate token for each.
- Let the patient add and remove connected organizations from a settings screen.
- Label every value with the organization it came from, and do not merge records across organizations without a clear rule.
- Track token status per organization, so one expired connection does not hide data from the others.
- Expect the same lab test to appear with different local names at different organizations.
Should your portal replace MyChart or sit beside it?
This decision sets the size of the project. A portal beside MyChart reads the patient's data, adds features MyChart does not have, such as a specialty program, a device dashboard or care plans in your own design, and links to MyChart for everything else. A portal that tries to replace MyChart has to rebuild scheduling, messaging, billing and proxy access, each through its own API and customer approval.
Most teams should start beside MyChart. The integration is the standard patient-facing path, the review is lighter, and patients keep the tool their health system already supports. Add writes one at a time when the customer is ready.
What slows a portal integration down?
- Registering more APIs than the portal uses. Epic asks you to include only the APIs you plan to call in production.
- Testing only in the sandbox. Epic's sandbox uses example data, and each customer's configuration differs.
- Unclear ownership on the customer side. A practice that uses a hospital's Epic instance needs that hospital's IT team.
- Patients without active MyChart accounts. Epic says customers provision MyChart accounts, so your onboarding has to send patients who lack one back to the health system.
- Missing security answers. Expect questions about hosting, encryption, every third-party service that touches data, and incident response.
On security, we sign a BAA before anyone on our team sees PHI and run a penetration test before launch, and we scope access so each clinician sees only their own patients. Those answers belong in the packet you send the health system.
We have shipped Epic and athenahealth integrations, and for any vendor platform we work from the vendor's documentation and sandbox. If you are planning a portal on Epic data and want to know which launch, scopes and writes it needs, talk to one of our engineers. Our free five-day technical audit ends with a written report.
Sources
- Epic on FHIR: documentation (patient-facing apps, standalone launch, automatic client distribution)
- Epic on FHIR: developer site and API listings
- open.epic: Developer Guide (Developer Resources)
- HL7 SMART App Launch 2.2.0: App Launch
- ONC (ASTP): §170.315(g)(10) Standardized API for patient and population services