HIPAA compliant software development: what it actually means in code
HIPAA compliance is one of those things that makes people nervous when they do not know what it involves, and frustrates experienced developers because so much of what is labeled "HIPAA compliant" is vague marketing with no technical substance behind it.
A hosting provider saying they are "HIPAA compliant" means they sign a BAA and handle the physical security of their data centers. That has nothing to do with whether your application is HIPAA compliant.
A developer saying they build "HIPAA compliant software" means something specific. Or it should. This page explains what HIPAA compliance actually requires in software, how I have implemented each requirement in production, and what mistakes to avoid.
What HIPAA actually regulates in software
HIPAA (Health Insurance Portability and Accountability Act) has three main rules relevant to software:
Governs how Protected Health Information (PHI) can be used and disclosed. For software, this mostly means your data access design: who can see what information, and under what circumstances.
Sets the technical, physical, and administrative safeguards required for electronic PHI (ePHI). This is what directly shapes how you build software. The Security Rule has required implementations (things you must do) and addressable implementations (things you must either do or document why they are not appropriate for your situation).
Requires covered entities and business associates to notify affected individuals and HHS when a breach of unsecured PHI occurs. For software, this means having the logging and monitoring in place to detect a breach and understand its scope.
Most developers focus on the Security Rule, which is right. The Privacy Rule shapes data access design, and breach notification is mostly a process question. The Security Rule is where the implementation details live.
The four technical safeguards HIPAA requires
The Security Rule's technical safeguards section defines what software must do to protect ePHI. There are four categories:
Only authorized people can access PHI. This means authentication (prove you are who you say you are) plus authorization (you can only see the data you are allowed to see). Role-based access control is the standard implementation. Each user role has a defined set of what they can read, create, update, and delete.
The software must record who accessed ePHI, when, and what they did. This is audit logging: every login, every record view, every create/update/delete action, every document download. The log should capture the user, timestamp, action type, and the record affected.
PHI must not be altered or destroyed in an unauthorized or undetected manner. This is about both security (preventing unauthorized changes) and data integrity (ensuring what is stored is what was intended). Checksums, audit trails, and access controls all contribute to integrity.
PHI must be protected when transmitted over networks. TLS encryption for all data in transit is the standard implementation. Any API call, any document download, any form submission must happen over HTTPS.
How I implement access controls in healthcare software
Access control in healthcare has to be more granular than most applications. "Admin" and "user" is not enough. You need a model that reflects the actual clinical roles.
In the Synectus Medico platform, the permission system has two layers:
Route-level protection
Certain pages are only accessible to certain roles. A billing-specific page is not accessible to a physician. An admin configuration page is not accessible to an attorney. Route protection checks the user's role from their JWT token before rendering the page.
Component-level permission keys
Each interactive UI element (create button, edit dialog, delete control) has a permission key. A centralized permission map defines which roles can access each key. When a user loads a page, the permission context is populated from their role. Components that require a permission the user does not have are removed from the DOM entirely, not just disabled or visually hidden.
This distinction matters. A visually disabled button can still be seen. A developer or a security researcher can see that the button exists, inspect its onclick handler, and potentially find a way to trigger the action. A button that does not exist in the DOM cannot be manipulated from the browser.
The API layer enforces the same access rules server-side. An attorney calling the patient list API receives only their own clients, because the API pre-filters by the attorney's ID from their JWT token. Even if the request is constructed manually without the frontend UI, the data isolation holds.
Audit logging in HIPAA-compliant software
Audit logging is probably the most underbuilt HIPAA technical requirement in healthcare software. A lot of systems log "user created record" without capturing what was in the record, or log API calls without capturing which specific patient record was accessed.
A proper audit log for healthcare software should capture:
In the Medico platform, every create, update, and delete action in the API layer generates an audit log entry automatically, through middleware rather than manual logging calls in each handler. This ensures nothing is missed because a developer forgot to add logging to a specific route.
Encryption: in transit and at rest
In transit encryption
In transit encryption means all data travels over HTTPS/TLS. This is table stakes. Any HTTP (non-TLS) traffic that carries PHI is a HIPAA violation. Configure your server to redirect HTTP to HTTPS. Use TLS 1.2 or higher. Do not allow weak cipher suites.
At rest encryption
At rest encryption means PHI stored in your database and file storage is encrypted. PostgreSQL supports encryption at the storage level. AWS RDS (managed PostgreSQL) encrypts storage by default when you enable it. AWS S3 buckets should have server-side encryption enabled.
Signed URL access control for documents
For document storage specifically, signed URL access control is important beyond encryption. Documents stored in S3 should not be publicly accessible. Instead, when a user needs to download a document, the API generates a time-limited signed URL. The URL grants temporary read access to that specific file for 15 to 30 minutes. After it expires, the link no longer works. This means a shared link or a link intercepted in transit does not become a permanent security vulnerability.
Session management: automatic logoff
HIPAA's Security Rule includes "automatic logoff" as an addressable implementation. The intent is to prevent an unattended workstation from leaving patient data exposed.
Technical implementation
The technical implementation: after a configurable period of inactivity, the user's session token expires. When the expired token is used in an API call, the API returns a 401 Unauthorized response. The frontend intercepts this via an API client interceptor (Axios interceptor, for example) and redirects the user to the login page.
Configurable per role
The configurable piece matters. Physicians in a busy clinic may need longer sessions because they move quickly between patients. Billing staff at a front desk may need shorter sessions because they step away frequently. The ideal implementation lets administrators configure the session timeout per role.
Multi-tenant data isolation as a HIPAA control
In a multi-tenant SaaS platform, HIPAA compliance requires that one clinic's data is completely isolated from another's. A breach at one tenant should not expose another tenant's data.
Subdomain-based tenant identification
The Medico platform implements subdomain-based tenant isolation. Each clinic accesses the platform through a unique subdomain. The subdomain value is extracted from the request and validated against the database. All database queries for that request include the tenant ID as a filter condition.
Row-level security as backup enforcement
Row-level security at the PostgreSQL level provides an additional enforcement layer. Even if an application-level bug somehow bypassed the API filtering, the database itself would not return records from a different tenant.
This isolation also matters for HIPAA Business Associate Agreements. When Clinic A signs a BAA with the platform provider, that BAA covers Clinic A's PHI. Clinic B's PHI is covered by a separate BAA. Data isolation ensures that each BAA relationship is clean.
What a Business Associate Agreement (BAA) means for software
A Business Associate Agreement is a contract between a HIPAA covered entity (clinic, hospital) and a business associate (software vendor, developer) that handles PHI on their behalf.
What a BAA covers
- What you can and cannot do with PHI
- Your obligation to safeguard PHI using appropriate safeguards
- Your obligation to notify the covered entity of a breach
- What happens to PHI when the contract ends
Sub-BAAs with vendors
As a healthcare software developer, you are almost certainly a business associate if your software stores, processes, or transmits patient health information. That means your clients need to sign a BAA with you before you handle their patients' data.
If you are building a healthcare SaaS product, you need a standard BAA template reviewed by a healthcare attorney. And your subcontractors who handle PHI (AWS, Twilio if you use SMS, your hosting provider) need to sign BAAs with you as well.
- AWS, Google Cloud, and Azure all offer BAAs as part of their enterprise agreements
- Twilio offers a BAA for HIPAA-covered use cases
- These sub-BAAs are part of your HIPAA compliance stack
Common HIPAA mistakes in software development
A few things I see repeatedly that create compliance risk:
⚠ Putting PHI in URL parameters
If a patient ID or record identifier appears in the URL as a query parameter, it can be logged in server logs, browser history, referrer headers, and analytics tools. Use POST requests for anything involving PHI. If you must use URL parameters, use opaque identifiers (UUIDs, not sequential integers).
⚠ Logging PHI in application logs
Console logs, error tracking tools, and application performance monitoring can capture request and response bodies. Make sure PHI is not included in log output. Scrub sensitive fields before logging.
⚠ Inadequate session expiry
Setting session tokens to never expire, or setting them to expire in 90 days, is a HIPAA risk. Sessions should expire after inactivity.
⚠ Shared user accounts
Each user should have their own account with their own credentials. Shared logins (everyone at the clinic uses the same password) make audit logs useless, because you cannot tell which specific person took an action.
⚠ Not enforcing access control at the API level
Hiding a UI element is not access control. If the underlying API endpoint returns data to anyone who calls it, regardless of role, the access control is not HIPAA compliant. Always enforce at the API level.
Frequently asked questions
HIPAA compliance in software is not a certification you get or a checkbox you check. It is a set of architectural decisions made throughout the development process. Access controls, audit logging, encryption, session management, and tenant isolation all need to be in the design from the beginning.
The good news is that HIPAA-compliant architecture is not fundamentally more complex than standard good security practices. It just requires being explicit and intentional about each safeguard rather than treating security as an afterthought.
If you are building a healthcare software product and want to make sure the compliance foundations are solid, a technical review of your architecture is worth doing early.
Request Architecture Review