Skip to content

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

HTTP
GET /fhir/R4/Condition?patient=123&clinical-status=active

Reverse-chain search, finding all patients with an active MedicationRequest for a given drug:

HTTP
GET /fhir/R4/Patient?_has:MedicationRequest:patient:medication.code=http://www.nlm.nih.gov/research/umls/rxnorm|860975

Bulk export of all Observations for population-health analysis (FHIR Bulk Data / $export):

HTTP
GET /fhir/R4/Patient/$export?_type=Observation

How the OAuth2 PKCE flow works with SMART on FHIR

  1. The client app generates a random code_verifier and derives a code_challenge from it (SHA-256, base64url-encoded).
  2. The app redirects the user to the authorization server with the code_challenge, requested scopes (e.g., patient/Observation.read), and a redirect_uri.
  3. The user authenticates and approves the requested scopes.
  4. The authorization server redirects back to the app with a short-lived authorization code.
  5. The app exchanges that code, along with the original code_verifier, for an access token at the token endpoint.
  6. The server verifies the code_verifier matches the code_challenge from 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.
  7. 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:

Text
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.

Book a call

Ready for software that finally fits?

Bring us your care model and find the right technical partner to build it with you.