When we built a HIPAA-compliant patient portal for a multi-provider medical practice in greater Boston, the starting point was familiar: five providers across two locations, roughly 150 patients a week, scheduling done entirely by phone, paper intake forms re-keyed by hand into the EHR, and a no-show rate near 22%. The portal we shipped in under 60 days cut administrative overhead by 40%, halved missed appointments, and brought check-in from nine minutes to under three — without migrating the practice off its EHR.
None of that came from the screens patients see. It came from the decisions underneath them: how patients prove who they are, where messages and documents live, how scheduling stays in sync with the EHR, and how data from half a dozen different systems gets into one place without leaking along the way. This article walks through those decisions. It's about engineering, not legal advice — for the compliance framework itself, see our companion piece on what HIPAA-compliant software architecture actually requires.
A patient portal is an integration project with a login screen
The first thing to accept about a patient portal is that almost none of the data it shows originates in the portal. Appointments live in the EHR or practice management system. Lab results may come from an outside lab. Insurance eligibility comes from a clearinghouse. Balances come from billing. In a real practice, that data reaches you through at least four different kinds of plumbing — and each one has its own HIPAA failure modes.
HL7 v2 feeds
HL7 version 2 is still how most EHRs announce that something happened: a scheduling message when an appointment is booked or moved, an admission or registration message when patient demographics change, a results message when a lab comes back. These messages are pipe-delimited, decades old, and slightly different at every site, because vendors and practices add their own custom segments. They're often sent over MLLP, a transport with no encryption of its own, so the connection has to run inside a VPN or TLS tunnel. Your parser has to tolerate site-specific quirks, acknowledge every message correctly so the sender doesn't resend or drop it, and handle the same message arriving twice. And the raw messages you keep for troubleshooting are PHI — they need the same encryption, access controls, and retention rules as everything else.
FHIR APIs
FHIR is the modern, REST-based alternative, and where it's available it's far nicer to work with: JSON resources for patients, appointments, and observations, with OAuth-based authorization through SMART on FHIR. The catch is that support is uneven. One EHR lets you read appointments but not write them; another exposes the resources you need only behind a paid developer program or a certification process; most enforce rate limits that a naive sync job will hit by Tuesday. In our portal, HL7/FHIR endpoints pull provider schedules and push appointment data back, so the EHR stays the system of record for clinical data. That decision — sync with the EHR, don't replace it — is what made a 60-day launch possible.
SFTP file drops
A surprising share of healthcare data still moves as files on a schedule: lab results, eligibility and claims files from clearinghouses, billing exports, and nightly CSVs from systems that have no API at all. SFTP is fine for this if it's treated as part of the PHI boundary rather than an afterthought. That means key-based authentication instead of shared passwords, IP allowlists, a HIPAA-eligible service such as AWS Transfer Family or a hardened host covered by your BAA, encryption of the files at rest, and a pipeline that processes each file exactly once, quarantines anything malformed, clears the landing folder after ingest, and records every file in the audit log. The classic failure isn't a hacked server — it's a folder of three years of unprocessed patient files nobody remembered was there.
Vendor APIs
Then there are the services wrapped around the portal: SMS and push notifications, payments, e-signature, video visits, email. Each one that creates, receives, maintains, or transmits PHI needs a Business Associate Agreement — and HHS's cloud computing guidance makes clear that applies even to a provider that only stores encrypted data it can't read. For the ones that won't sign — or where you'd rather not depend on one — the answer is to keep PHI out entirely. A reminder that says "You have an upcoming appointment. Log in to view details" tells the patient everything they need and tells an SMS provider nothing.
GraphQL as the read layer
With data arriving from all of those sources, it helps to give the patient app and the staff dashboard one consistent API that hides where each piece came from. GraphQL is a good fit: one schema for appointments, messages, documents, and balances, and each client asks for exactly the fields it needs. But GraphQL changes where security has to live. A single request can touch dozens of records across several types, so authorization has to happen in every resolver — "this patient may see this appointment" — not just once at the endpoint. Turn off schema introspection in production, enforce query depth and complexity limits, prefer persisted queries from your own apps, keep PHI out of shared or CDN caches, scrub error messages so they never echo record data, and make sure every record a request returns can be traced in the audit log — whether that happens in the resolvers or in the service layer underneath them — rather than logging one entry per HTTP request. The OWASP GraphQL Cheat Sheet is a good checklist for the rest.
The pattern that holds all of this together is simple to describe and tedious to build: every inbound path lands in one integration layer that validates, de-duplicates, and records where each piece of data came from and when. The portal reads only from its own encrypted store, never live from five systems at once. And when the portal and the EHR disagree, the EHR wins.
The screens are the easy part. The hard part is that patient data already lives in five places, arrives in four formats, and every path it takes to the patient has to be encrypted, logged, and reconciled.
Authentication: who is this, and whose record can they see?
The HIPAA Security Rule's technical safeguards require unique user identification and person-or-entity authentication. In a portal, that turns into three harder questions. First, enrollment: how do you know the person creating an account is the patient in your chart? Matching on name and date of birth alone invites the wrong person into the wrong record. Invitation codes issued by the practice at a visit, or identity verification at sign-up, are much safer. Second, multi-factor authentication. The current Security Rule requires appropriate authentication and access controls but does not universally mandate MFA. HHS proposed more explicit cybersecurity requirements in January 2025, including MFA and encryption. Although those changes are not yet final, MFA should be a standard design choice for any new patient portal. Third, account recovery, which is where most portal account takeovers actually happen. A "forgot password" flow that emails a reset link to an address someone changed yesterday undoes every other control.
Then comes proxy access, which most first drafts of a portal forget. Parents need access to young children's records; adolescents are often entitled to confidential care their parents can't see; adult children manage appointments for aging parents. Each of those is a different permission model, and all of them have to be explicit, time-bounded where appropriate, and auditable. Add automatic logoff after inactivity, and you have the authentication layer HIPAA actually expects.
Secure messaging that stays secure
Secure messaging means the message itself lives inside the portal, behind authentication, and everything outside the portal is just a nudge. Push notifications, texts, and emails should say "You have a new message from your care team" — never the content, never the diagnosis, never the name of the provider if that alone reveals something sensitive. On the staff side, messages should route to a care-team pool rather than a single inbox, so nothing sits unanswered while one person is on vacation. Show patients clearly that the portal isn't for emergencies, set expectations for response time, and decide early which messages become part of the medical record — because if they do, they need a path back into the EHR.
Scheduling: the EHR owns the truth
Online scheduling looks like a calendar widget. In practice, the real availability lives in the EHR or practice management system, shaped by provider templates, visit types, new-versus-established patient rules, and locations. The portal has to read that availability, offer only slots a patient is actually allowed to book, and write the appointment back before confirming it — handling the race when two patients grab the same slot, or when front-desk staff book it by phone at the same moment. Reminders do the rest of the work. In our portal, automated SMS and push reminders drove a 50% drop in no-shows within 90 days, and they did it without putting PHI in a single text message.
Document uploads: insurance cards, IDs, and intake forms
Patients upload photos of insurance cards and IDs, signed consent forms, and outside records. Every one of those files is PHI. Store them in private, encrypted object storage — never behind a public URL — and hand them out only through short-lived, signed links generated after an authorization check. Validate file types by content rather than by extension, scan for malware before any staff member opens a file, and strip image metadata: a phone photo of an insurance card can carry the GPS location of the patient's home. Then set a retention policy, because files nobody needs anymore are pure risk.
The audit log HIPAA actually depends on
Infrastructure logs like AWS CloudTrail tell you who changed a server. They don't tell you who looked at a patient's chart. A portal needs its own application-level audit log that records, for every access:
- Who — the patient, proxy, staff member, or integration that acted.
- What — viewed, created, changed, exported, or disclosed, and which record.
- When and from where — a timestamp and the source of the request or inbound feed.
Write it to append-only storage that application code can't edit, and include integration traffic — HL7 messages, SFTP files, API pulls — not just clicks in the app.
A patient portal HIPAA requirements checklist
If you only take one thing to a vendor meeting or a budget review, take this. Some items are explicit HIPAA requirements; others are what a security reviewer will reasonably expect from any new portal.
- Identity verification — confirm a new account belongs to the right patient chart before it shows any data.
- Multi-factor authentication — for patients and staff alike.
- Proxy access — explicit, auditable permissions for parents, caregivers, and adolescents' confidential care.
- Secure communications — messages and documents stay behind login, notifications carry no PHI, and every connection uses TLS.
- EHR integration — the EHR stays the system of record, and every feed (HL7, FHIR, SFTP, vendor APIs) is encrypted and logged.
- Encryption — at rest and in transit, including file storage, backups, and raw integration messages.
- Audit trails — an application-level record of who viewed or changed what, and when.
- Business Associate Agreements — with every vendor that creates, receives, stores, or transmits PHI.
- Backups and recovery — encrypted backups, tested restores, and a documented contingency plan.
- Risk analysis — a current, documented security risk analysis, updated whenever the system changes.
- Incident response — a written plan for detecting, containing, and reporting a breach, including notification deadlines.
Build vs. buy: what you're actually paying for
There are three realistic options, and none is free.
- Your EHR vendor's portal — often the cheapest place to start, and the integration is already done. You get the vendor's design, workflow, and roadmap, and sometimes an upgrade you didn't plan for: the practice we worked with would have had to migrate to a new EHR platform version to use theirs.
- A white-label portal product — fast to launch, usually priced per provider per month, and covered by the vendor's BAA. It works well when your data lives mostly in one EHR it already supports, and less well when you need SFTP feeds, custom intake, or a workflow it doesn't model.
- A custom portal — built around how your practice actually works and able to pull from every source you have. You own the security, the BAAs with each vendor in the data path, and the ongoing maintenance.
For a custom build, the cost is driven less by screens than by integration and compliance: how many data sources you have and what formats they speak, whether your EHR charges for API access or requires certification, how complicated your proxy and identity rules are, whether you need native mobile apps or a web app is enough, and the ongoing work — a current security risk analysis, penetration testing, monitoring, and dependency updates — that keeps a portal compliant after launch. That last category is the one most budgets leave out.
A patient portal isn't priced by its screens. It's priced by how many systems it has to talk to, and how carefully each of those conversations has to be protected.
Where this leaves you
A HIPAA-compliant patient portal isn't a product you install or a checkbox you tick. It's a set of engineering decisions: how patients prove who they are, where messages and files live, how every source of data — HL7 feeds, FHIR APIs, SFTP drops, vendor APIs — reaches one audited store, and how the API on top of it decides what each person may see. Get those right and the screens almost build themselves. Get them wrong and no amount of interface polish makes the portal safe.
If you're weighing your EHR's portal against a custom build, start by mapping where your patient data actually lives today. That map usually answers the build-versus-buy question for you.