Headless EHR implementation checklist: 5 steps with acceptance criteria

Implementing a headless EHR comes down to five steps, in dependency order: identity and auth, the FHIR data model, eventing, observability and API governance. Each one below ends with an acceptance criterion, a test that tells you the step is actually done rather than “mostly working.” It’s written for CTOs and engineering leads who have already decided to go headless and now need to build it.
This is the hands-on companion to Headless EHRs: a deep dive into the technical and market landscape, which covers what a headless EHR is, how the main platforms compare and how to decide between building and buying. Start there if you haven’t chosen a platform yet; come back here once you have.
The 5-step headless EHR implementation checklist
Numbered, in dependency order. Each step has a concrete acceptance criterion so you know when it’s actually done.
-
Identity and auth
- OAuth 2.0 / OpenID Connect implemented with PKCE for public/mobile clients
- SMART on FHIR scopes defined per app (patient-level vs. user-level access)
- Access tokens short-lived (≤15 min is a common baseline) with refresh-token rotation
- Acceptance criteria: a third-party app can complete an OAuth2/PKCE flow end-to-end against your sandbox and receive a scoped token it can’t use outside its granted resources.
-
Data model / FHIR resources
- Core resource types mapped (Patient, Encounter, Observation, Condition, MedicationRequest, at minimum)
- US Core (or applicable regional) profile conformance validated
- Terminology bindings in place for SNOMED CT, LOINC, RxNorm where applicable
- Acceptance criteria: a FHIR validator run against your resource instances returns zero conformance errors for your chosen profile.
-
Eventing
- Message broker or FHIR Subscriptions configured for state changes that matter downstream
- Saga (or equivalent compensating-action pattern) defined for any transaction spanning more than one service
- Acceptance criteria: a failure injected mid-transaction in a test environment triggers the compensating action and leaves no orphaned state.
-
Observability
- Distributed tracing across service boundaries
- Centralized, structured logging with no PHI in log payloads (use opaque record IDs, not names or DOBs)
- Alerting on auth failures, latency spikes, and FHIR validation errors
- Acceptance criteria: a single request can be traced end-to-end across every service it touches, and a log audit confirms zero raw PHI fields in log output.
-
Governance
- API versioning strategy documented (URL-based, header-based, or content-negotiation)
- Deprecation policy with a minimum notice period for breaking changes
- Automated compatibility tests running in CI against the previous API version
- Acceptance criteria: a breaking change cannot merge to main without a corresponding version bump and a passing compatibility test suite.
Example FHIR queries for a headless EHR
Fetch a patient’s active conditions:
GET /fhir/R4/Condition?patient=123&clinical-status=activeReverse-chain search, finding all patients with an active MedicationRequest for a given drug:
GET /fhir/R4/Patient?_has:MedicationRequest:patient:medication.code=http://www.nlm.nih.gov/research/umls/rxnorm|860975Bulk export of all Observations for population-health analysis (FHIR Bulk Data / $export):
GET /fhir/R4/Patient/$export?_type=ObservationHow the OAuth2 PKCE flow works with SMART on FHIR
- The client app generates a random
code_verifierand derives acode_challengefrom it (SHA-256, base64url-encoded). - The app redirects the user to the authorization server with the
code_challenge, requested scopes (e.g.,patient/Observation.read), and aredirect_uri. - The user authenticates and approves the requested scopes.
- The authorization server redirects back to the app with a short-lived authorization
code. - The app exchanges that
code, along with the originalcode_verifier, for an access token at the token endpoint. - The server verifies the
code_verifiermatches thecode_challengefrom step 2. This is what stops a stolen authorization code from being redeemed by anyone other than the app that started the flow, since only the original app holds the verifier. - The app receives a short-lived access token (and, if requested, a refresh token) scoped exactly to what the user approved.
Enforcing care-team access with an OPA/Rego policy
A simple example enforcing that a user can only read Observation resources for patients within their assigned care team:
package fhir.authz
default allow = false
allow {
input.method == "GET"
input.resource_type == "Observation"
input.user.care_team[_] == input.resource.patient_id
}This runs at the API gateway as a policy-enforcement point: every request carries the user’s care-team assignments and the resource’s patient reference, and the policy engine evaluates the rule before the request reaches the FHIR store. Access is denied by default unless the rule explicitly allows it.
Conclusion
The order is the point. Identity and the FHIR data model come first because every later step depends on them: you can’t scope events, trace requests or version an API whose resources and permissions aren’t settled. Governance comes last in the list, but it only holds if it’s enforced in CI from the first release, not added once clients depend on your API.
The acceptance criteria turn “done” into something you can test, which is what keeps a distributed, regulated system from drifting. And the checklist only pays off once the platform choice is right: if you’re still weighing Medplum against a configurable SaaS EHR, or building against buying, read Headless EHRs: a deep dive into the technical and market landscape first.
Frequently Asked Questions
What are the steps to implement a headless EHR?
Five, in dependency order: identity and auth (OAuth 2.0 / OpenID Connect with PKCE and SMART on FHIR scopes), the data model (core FHIR resources validated against US Core or your regional profile), eventing (a message broker or FHIR Subscriptions, with Sagas for multi-service transactions), observability (distributed tracing, structured logs with no PHI, alerting) and governance (API versioning, a deprecation policy and compatibility tests in CI).
Why use PKCE with SMART on FHIR?
Public and mobile apps can’t keep a client secret. PKCE replaces it with a one-time code_verifier that only the app that started the login holds, so a stolen authorization code can’t be exchanged for an access token by anyone else.
How do you keep PHI out of headless EHR logs?
Log opaque record IDs instead of names, dates of birth or other identifiers, use structured logging so every field is explicit, and audit log output regularly. The acceptance criterion is a log audit that finds zero raw PHI fields.
Related articles

Article · 21 min read
Headless EHRs: a deep dive into the technical and market landscape
The architecture, implementation challenges and market opportunities of headless EHRs.
21 min read

Article · 3 min read
How to implement SMART on FHIR authentication with Topology Health
A React Native tutorial on OAuth2 PKCE login, with an Epic integration demo and code.
3 min read




