Forem: mock health

Testing FHIR Integrations Without a Hospital

mock health — Tue, 14 Apr 2026 21:24:38 +0000

You're building a FHIR integration. You need to test it against data that looks like what a hospital actually produces.

You don't have access to a hospital.

This is the catch-22 that every FHIR startup lives in for 6-12 months. You can't get production EHR access without a working, tested integration. You can't build one without production-quality data. Epic's app marketplace review takes 2-4 months. Oracle Health takes 3-6. And all of them want evidence that your software works before they give you the data to prove it.

The Testing Pyramid for FHIR

Tier 1: Parse and Validate

Does your FHIR output conform to US Core profiles? You don't need a server for this. The HAPI FHIR Validator runs locally:

java -jar validator_cli.jar patient-bundle.json \
  -ig hl7.fhir.us.core#6.1.0 \
  -profile http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient

Run this in CI on every commit. It catches malformed resources, missing required fields, and profile violations.

Tier 2: Integration

This requires a running FHIR server with SMART on FHIR auth. You need to test the full request lifecycle: discovery, authorization, token exchange, scoped queries.

Things that break at this tier and nowhere else:

Your search uses Observation?category=laboratory but the server indexes it as Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
Your SMART scopes request patient/Observation.read but the server only grants patient/Observation.rs — read and search are separate grants
Patient/$everything returns 2,000 entries with pagination links your client doesn't follow

Tier 3: Realistic

This is the tier most teams skip. You need patients that look like real patients:

What you're testing	What the data needs
Lab trending UI	3+ years of longitudinal labs with reference ranges
Medication reconciliation	8-12 active medications with start dates and dosages
Problem list display	5-15 active conditions with SNOMED coding
Prior auth workflow	Complex patients who actually get denied

If your Tier 3 data is a single patient named "Test Cancer" with one condition, your tests aren't testing anything.

Your Options

Option 1: Local HAPI + Synthea

You've probably already done this. HAPI in Docker, a handful of Synthea patients, maybe a script that generates 10 bundles.

docker run -p 8080:8080 hapiproject/hapi:latest
cd synthea && ./run_synthea -p 10

When this is enough: Early prototyping, Tier 1 validation.

When it isn't: No SMART auth. Synthea defaults produce patients with single conditions and no clinical depth. At some point the test data pipeline becomes its own project — one you maintain alongside the product you're actually building.

Option 2: Vendor Sandboxes

Open Epic, Oracle Health Code, SMART Health IT Sandbox.

When this is enough: Testing OAuth against a real vendor's auth server.

When it isn't: Open Epic gives you 8 patients with sparse data. No comorbidity patterns. No longitudinal labs. No imaging. No clinical notes. We wrote a whole post about this.

Option 3: Clinically Realistic Sandbox

A FHIR server with SMART auth and patients generated from real clinical patterns.

curl -s https://api.mock.health/fhir/Condition?patient=example \
  -H "Authorization: Bearer $TOKEN" | jq '.entry[].resource.code.coding[0].display'

"Type 2 diabetes mellitus"
"Essential hypertension"
"Chronic kidney disease, stage 3"
"Hyperlipidemia"
"Diabetic retinopathy"

These conditions travel together because the generation engine learned that pattern from real CMS claims data. Compare to Open Epic: "Pain in throat".

What Changes When You Get Production Access

Your sandbox-tested code won't ship unmodified. You'll encounter vendor-specific extensions, data quality variance (plan for trash), and an opaque app review process.

But the architecture you built against a sandbox will survive. The specific data handling will need adaptation. That's normal — sandbox testing builds the 90% that doesn't depend on vendor-specific behavior.

Tier	Tool	Catches
1	HAPI Validator in CI	Malformed resources, profile violations
2	SMART-enabled sandbox	OAuth bugs, search parameter issues
3	Realistic synthetic data	Logic errors with complex patients

Run Tier 1 on every commit. Run Tier 2 when you change auth or query logic. Run Tier 3 before every demo and before you apply for production access.

mock.health — SMART-enabled FHIR sandbox with clinical density to get through Tier 3 testing. API key in 60 seconds →

Three Ways to Build a Multi-Tenant FHIR Server

mock health — Sun, 12 Apr 2026 23:35:03 +0000

You're building a FHIR platform that serves multiple customers. Each one needs isolated data through the same API. There's no best practice for this — Darren Devitt's FHIR Architecture Decisions calls multi-tenancy a "deal breaker" requirement that can eliminate entire classes of FHIR servers.

Three models exist. We've built two of them in production with HAPI FHIR.

Model 1: Separate Database Per Tenant

Each tenant gets their own database schema — or for true physical isolation, their own database host.

What you get: Strongest isolation. Independent scaling. DROP SCHEMA to delete a tenant. Compliance teams love it (especially separate hosts).

What breaks: You're managing N connection pools, N migrations, N backups. HAPI's HikariCP defaults to 10 connections — we exhausted the pool with 8 concurrent workers and left HAPI in a zombie state. Cold starts per tenant add 30-45 seconds when a database hasn't been accessed recently.

When to use it: Regulations mandate physical separation. Tenants are large enough to justify the overhead.

Model 2: Shared Database, Partitioned Tables

One database, but every resource row gets a PARTITION_ID column. HAPI supports this natively:

partitioning:
  database_partition_mode_enabled: true
  request_tenant_partitioning_mode: true
  allow_references_across_partitions: true

Creating a partition:

POST /fhir/$partition-management-create-partition
{"resourceType": "Parameters", "parameter": [
  {"name": "id", "valueInteger": 101},
  {"name": "name", "valueCode": "tenant_acme"}
]}

What you get: Logical isolation at the storage layer. One database to manage. Cross-partition references for shared data (practitioner directories, formularies).

What breaks: HAPI bugs surface here. #1099: patient=UUID triggers "Non-unique ID" errors — fix by rewriting to patient:Patient._id=UUID. #6665: bulk export background jobs lose partition context entirely — we rebuilt the Bulk Data Access IG in Python.

No built-in access control. HAPI doesn't know who's calling — your API gateway handles auth and routing.

When to use it: Many tenants, moderate data volumes. You want logical isolation without N databases.

Model 3: Shared Database, Tag-Based Filtering

One database, no partitions. Every resource gets a meta.tag for its tenant. Your gateway appends _tag=tenant_acme to every query.

extra_params["_tag"] = f"https://yourapp.com/tenant|{tenant_id}"

What you get: Simplest to implement. Zero overhead per tenant. Works with any FHIR server, not just HAPI.

What breaks: No real isolation — the boundary is your gateway's tag-filtering logic. A missed _tag parameter on one endpoint leaks data across tenants.

Worse: HAPI ignores _tag on instance reads. GET /fhir/Patient/abc-123 returns the resource regardless of tags. You need post-fetch verification:

resource = resp.json()
resource_tags = {t["system"] + "|" + t["code"] for t in resource.get("meta", {}).get("tag", [])}
if not resource_tags.intersection(allowed_tags):
    return 404

When to use it: Prototyping. Internal tools. Small deployments. A starting point before migrating to partitions.

How to Choose

Concern	Separate DB	Partitions	Tags
Isolation	Strongest	Logical (storage)	Logical (query)
Compliance	Happy	Usually OK	Nervous
Ops cost per tenant	High	Low	Zero
Performance isolation	Full	Shared DB	Shared everything
HAPI bugs	Fewer	More	Fewer
Works with any server	Yes	HAPI-specific	Yes
Instance read safety	Inherent	Inherent	Post-fetch check

The direction of migration matters: you can move from tags → partitions → separate databases, but not easily the other way. Start with the simplest model that meets your compliance requirements.

Whichever model you choose, the FHIR server handles storage. Auth, routing, and access control are your gateway's job. We wrote about what that gateway looks like.

mock.health handles multi-tenant isolation so you can focus on your integration. Isolated FHIR data with SMART auth — no partition management required. Try it free →

Building a FHIR API Gateway: What HAPI Won't Do for You

mock health — Fri, 10 Apr 2026 22:56:33 +0000

HAPI is a FHIR storage engine. It validates resources, indexes search parameters, and returns Bundles. What it does not do: authenticate users, enforce per-tenant access control, generate correct URLs behind a reverse proxy, or stream large responses without buffering.

We run FastAPI in front of HAPI on Google Cloud Run. Here are the five things the gateway does that HAPI can't.

1. Auth Injection: One Hook, Every Request

In production, HAPI sits behind Cloud Run's IAM layer. Every request needs a GCP identity token. The pattern: an httpx event hook that fires before every outbound request.

async def _inject_hapi_auth(request: httpx.Request):
    token = await get_id_token(audience_url)
    request.headers["Authorization"] = f"Bearer {token}"

The bug we hit: auth injection was per-route. The main proxy had it. Portal routes didn't. Everything worked locally (no IAM). Four endpoints returned 403 in production.

Lesson: Auth belongs on the HTTP client, not on individual routes. One hook, one place, every request.

2. The `--proxy-headers` Trap

This will save you a day if you're running FastAPI behind any load balancer.

Cloud Run terminates TLS. Your app gets HTTP. The load balancer passes X-Forwarded-Proto: https. Uvicorn ignores this by default. So request.base_url returns http://.

The cascade:

SMART discovery advertises http:// token endpoint
Client POSTs auth code to http:// URL
Cloud Run 302 redirects HTTP → HTTPS
302 converts POST to GET (per HTTP spec)
Token endpoint gets GET → 405 Method Not Allowed

Nine places in our code use request.base_url. All nine broke. The fix:

CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000",
     "--proxy-headers", "--forwarded-allow-ips", "*"]

If you're running uvicorn behind any reverse proxy and generating URLs from request.base_url, you need these flags. You won't catch this locally.

3. Tag-Based Access Control

HAPI has no per-user access control. Our gateway appends _tag parameters to scope searches by tenant/dataset.

The gotcha: HAPI ignores _tag on instance reads. GET /fhir/Patient/abc-123 returns the resource regardless of tags. Our gateway does post-fetch verification — fetch the resource, check its tags, return 404 if they don't match.

resource_tags = {t["system"] + "|" + t["code"] for t in resource.get("meta", {}).get("tag", [])}
if not resource_tags.intersection(allowed_tags):
    return 404

Not ideal — the resource is fetched and discarded. But HAPI doesn't support tag filtering on instance reads.

4. Streaming Large Responses

A FHIR $everything can return megabytes. Don't buffer it.

resp = await client.send(req, stream=True)
return StreamingResponse(
    resp.aiter_bytes(),
    status_code=resp.status_code,
    media_type="application/fhir+json",
)

One gotcha: if HAPI returns 503, detect it before starting the stream. Once you've started a StreamingResponse, you can't change the status code.

5. The Catch-All Route Ordering Trap

Our FHIR proxy has a catch-all: /fhir/{path:path}. This matches everything — including /fhir/Patient/$export and /fhir/DocumentReference/$docref, which have dedicated handlers.

If the catch-all mounts first, those routes are unreachable.

# Order matters
app.include_router(bulk_export_router)  # most specific
app.include_router(docref_router)
app.include_router(fhir_router)         # catch-all last

Sounds obvious. Costs an afternoon when you add a new router six months later and forget.

Build the Gateway First

If you're deploying a FHIR server to production, build the gateway layer before you build features on top. Auth, URL generation, access control, streaming, and route safety affect every endpoint you'll add later. The FHIR server stores data. The gateway decides who sees it.

mock.health handles the gateway — SMART auth, access control, streaming — so you can focus on your application. Try it free →

The Contents of That Dumpster Are Private

mock health — Mon, 06 Apr 2026 23:09:23 +0000

Nikhil Krishnan wrote a great piece recently arguing that open source is healthcare's moment. The business models exist (Red Hat, GitLab). AI is lowering the contribution barrier. The ecosystem is ready.

He's right. But there's a punchline missing from the open-standards conversation that anyone who's actually built against healthcare APIs knows intimately:

The standard exists. Nobody follows it the same way.

FHIR (Fast Healthcare Interoperability Resources) is the anointed standard. ONC mandates it. CMS requires it for payer Patient Access APIs. Every major EHR vendor will tell you they support it. And technically, they do — the way a restaurant "supports" vegetarians by offering a side salad.

Same Patient, Different Reality

Flexpa recently published a fascinating comparison: the same patient's health data pulled through two different API pathways. The results should make anyone building healthcare software nervous:

TEFCA path: 192 FHIR resources, but only 1 condition — "pain in throat"
ONC g(10) path: 166 resources, 11 conditions including rhinitis — but missed a documented cat dander allergy entirely

Same patient. Same standard. Wildly different clinical picture. If you were building a care coordination app, which version of this patient would you trust?

This isn't an edge case. It's the norm.

The Spec Says One Thing. Production Says Another.

The January 2026 deadline for USCDI v3 and US Core 6.1.0 was supposed to fix this. Certified health IT modules must now support the latest FHIR profiles with richer data elements. On paper, progress.

In practice:

Major state Medicaid agencies — Arizona, Colorado, Illinois, Indiana, Massachusetts, New York, Pennsylvania, Texas — remain non-compliant
No BCBS plan operated by HCSC has successfully had a patient complete authorization and FHIR data retrieval
53 payers list refresh token support in their SMART configurations but don't actually issue refresh tokens
UnitedHealthcare has nearly 100 patients who simply cannot access their own data through the mandated API

These aren't obscure edge cases. These are the largest payers and state programs in the country.

The Normalization Tax

Even when the APIs work, the data that comes back requires heavy lifting before it's usable.

Zus Health reports that pulling records from clinical networks yields about 200 documents per patient, mapping to over 1,000 raw FHIR resources. Conditions arrive as a grab bag of ICD-9, ICD-10, and SNOMED codes — sometimes all three for the same condition. Without normalization, deduplication, and enrichment, the volume is pure noise.

Particle Health built an entirely proprietary CCDA-to-FHIR converter because open source libraries didn't meet their quality bar.

This is the dirty secret: an entire category of healthcare infrastructure companies exists primarily to clean up the mess that "standardized" data exchange creates. The standard is the floor, not the ceiling — and the floor has holes in it.

Plan for Trash

FHIR is a good standard. US Core is a good implementation guide. The ONC keeps tightening the spec — USCDI v3, US Core 6.1.0, SMART App Launch 2.0. But tighter specs only help if implementations actually conform. Right now, "FHIR-compliant" is a checkbox on a certification form, not a meaningful guarantee that the data you receive will be complete, consistent, or even parseable.

So here's the engineering takeaway: stop hoping for clean data. Plan for trash.

Every application that consumes FHIR from external systems needs a validation layer that isn't optional:

Profile validation on ingest. Every resource that crosses your system boundary gets validated against the US Core profile you expect. Not just schema validation — profile-level.
Completeness checks per data class. USCDI defines 22 data classes. When you pull a patient's record, how many are actually populated? Track and surface that distinction.
Automated regression testing against real-world variance. Your integration tests shouldn't run against a single pristine FHIR server. They should run against data that looks like what production actually sends — missing fields, mixed code systems, DSTU2 holdovers.

The companies actually moving the needle in interoperability — Flexpa, Zus, Particle, Onyx — all learned this the hard way. They built proprietary normalization, deduplication, and validation pipelines because the alternative was shipping broken products. The standard isn't bad. Conformance is just unreliable.

The Dumpster Metaphor, Extended

The meme says the contents of the dumpster are private. That's the HIPAA joke, and it's funny. But the deeper joke is:

Even if you get permission to open the dumpster, what's inside is still trash.

Don't wait for the spec to get stricter, or for ONC enforcement to get teeth, or for vendors to suddenly care about data quality. Build like you know the dumpster is full of trash — because it is — and validate everything that comes out of it.

Which means your test data needs to look like what production actually sends — not pristine sandbox patients with perfect coding. If your integration tests pass against clean data and break against the dumpster, your tests are lying to you.

mock.health generates FHIR data with the clinical density and variance you'll see in the real world. Free tier, no sales call →

How to Make Claude Write Valid Synthea Modules

mock health — Fri, 03 Apr 2026 22:24:49 +0000

Synthea has 85 disease modules. Each one is a JSON state machine that generates encounters, conditions, labs, medications, and procedures for a specific disease. If you need a condition Synthea doesn't cover — celiac disease, migraine, GERD, whatever — you author a new module.

The module format is learnable. The hard part is the medical codes.

Every module embeds SNOMED codes for conditions, LOINC codes for labs, and RxNorm codes for medications. Ask an LLM to write a celiac disease module and it'll generate SNOMED code 396331005. That's correct. Ask it for a duodenal biopsy and it might generate 12866006. Looks right. Validates as a real SNOMED code. It's actually pneumococcal vaccination.

You can't tell a valid code from a hallucinated one by looking at it. The only way to know is to check it against a terminology server. This post teaches that workflow, and we published a Claude Code skill that automates it.

Why You'd Want Custom Modules

We generated 10,000 patients from a fresh Synthea clone and compared against CDC benchmarks:

Coronary heart disease: 0%. Alzheimer's: 0%. Entire disease categories missing from 10,000 patients. Each module runs independently, so conditions don't interact the way real diseases do. We wrote about this in depth in how we validate synthetic data.

An average 80+ year-old Synthea patient has 74 active conditions. The top 1% of real Medicare patients have about 8. Most are social determinants and administrative codes, not diseases.

If your use case needs a disease that Synthea's 85 modules don't cover, you're authoring a module.

The Module Format in 60 Seconds

A Synthea module is a JSON file with a name, a states object, and a gmf_version. Each state has a type and a transition. Here's the smallest useful module:

{
  "name": "Example Condition",
  "states": {
    "Initial": {
      "type": "Initial",
      "distributed_transition": [
        { "distribution": 0.01, "transition": "Onset" },
        { "distribution": 0.99, "transition": "Terminal" }
      ]
    },
    "Onset": {
      "type": "ConditionOnset",
      "codes": [{ "system": "SNOMED-CT", "code": "??????", "display": "??????" }],
      "direct_transition": "Terminal"
    },
    "Terminal": { "type": "Terminal" }
  },
  "gmf_version": 2
}

The ?????? is the problem. What SNOMED code goes there?

State types you'll use: Initial, Terminal, Encounter/EncounterEnd, ConditionOnset/ConditionEnd, MedicationOrder/MedicationEnd, Observation, Procedure, Guard, Delay, SetAttribute.

Transitions: direct_transition (always), conditional_transition (if-then), distributed_transition (probabilistic), complex_transition (conditions + probabilities).

The Code Problem

System	What it codes	Example
SNOMED-CT	Conditions, procedures, findings	`396331005` = Celiac disease
LOINC	Lab results, vital signs	`31017-7` = tTG IgA antibody
RxNorm	Medications	`310325` = Ferrous sulfate 325mg

LLMs pattern-match these codes from training data. They don't look them up. For common conditions, usually right. For anything less common, the LLM generates a plausible number that might not exist.

The fix: tx.fhir.org, a free public FHIR terminology server. No account needed. One curl call validates any code:

curl -s "https://tx.fhir.org/r4/CodeSystem/\$validate-code?\
system=http://snomed.info/sct&code=396331005" \
  | jq '.parameter[] | select(.name=="result" or .name=="display")'

{ "name": "result", "valueBoolean": true }
{ "name": "display", "valueString": "Coeliac disease" }

And to find the right code:

curl -s "https://tx.fhir.org/r4/ValueSet/\$expand?\
url=http://snomed.info/sct?fhir_vs&filter=celiac+disease&count=5" \
  | jq '.expansion.contains[] | {code, display}'

This is what separates a working module from one that generates corrupt FHIR.

The Skill

We published a Claude Code skill that automates this workflow:

claude install github:mock-health/samples/synthea-module-skill
claude "/synthea create a celiac disease module"

The skill follows six steps:

Check existing modules — avoids duplicating what's already there
Research the condition — prevalence, diagnostic criteria, treatment
Look up every code — validates against tx.fhir.org before writing
Generate module JSON — following Synthea's exact schema
Build and test — ./gradlew build -x test + ./run_synthea -m <name> -p 1
Inspect output — checks the generated FHIR bundle

The SKILL.md contains the full module schema reference, code system mappings, grounding rules, and common pitfalls.

Working Example: Celiac Disease

Every code validated against tx.fhir.org:

Concept	System	Code	Display
Celiac disease	SNOMED-CT	`396331005`	Coeliac disease
EGD	SNOMED-CT	`76009000`	Esophagogastroduodenoscopy
Duodenal biopsy	SNOMED-CT	`235261009`	Biopsy of duodenum
Gluten free diet	SNOMED-CT	`160671006`	Gluten free diet
Iron deficiency anemia	SNOMED-CT	`87522002`	Iron deficiency anemia
tTG IgA antibody	LOINC	`31017-7`	Tissue transglutaminase IgA Ab
Ferritin	LOINC	`2276-4`	Ferritin [Mass/volume] in Serum or Plasma
Ferrous sulfate	RxNorm	`310325`	ferrous sulfate 325 MG Oral Tablet

The state machine:

Initial → Age_Guard (wait until age 2)
  → Prevalence_Check (monthly, age-stratified probability)
    → Symptom_Onset → Diagnostic_Encounter
      → tTG IgA test → Referral (2-6 weeks)
        → Endoscopy + Duodenal biopsy
          → Celiac_Diagnosis → Gluten-free diet
            → 50%: Iron deficiency → Ferrous sulfate
              → Annual monitoring (tTG IgA + ferritin)

The module uses complex_transition for age-stratified onset — childhood and ages 30-50 get different probabilities. The full module JSON is about 200 lines. Drop it into synthea/src/main/resources/modules/ and run:

cd synthea
./gradlew build -x test
./run_synthea -m celiac_disease -p 10 -s 42
jq -r '.entry[].resource.resourceType' output/fhir/*.json | sort | uniq -c | sort -rn

For Deeper Work

/fhir Claude Code skill — FHIR R4/R5, IGs, FSH, SMART on FHIR, validation
Inferno — ONC FHIR server compliance testing
Synthea Module Builder — GUI for visual module authoring
tx.fhir.org — public FHIR terminology server (free, no account)

The module format is learnable. The vocabulary problem is solvable. Ground your codes, and don't trust any medical code an LLM generates from memory — including ours. We built mock.health because we hit the limits of module-level fixes. Population-level realism requires a different architecture entirely. Free tier, API key in 60 seconds →

Build a SMART on FHIR App in 30 Minutes

mock health — Thu, 26 Mar 2026 20:55:05 +0000

SMART on FHIR is how apps talk to electronic health records. It's OAuth 2.0 with a few healthcare-specific conventions: a discovery document that tells your app where to authenticate, scopes that map to FHIR resource types, and a launch context that tells you which patient you're looking at.

This tutorial follows SMART App Launch STU2.1 — the current published standard. If you've built an OAuth login flow before, you already understand 80% of it. The other 20% is what this covers.

We're going to build a standalone SMART app that authenticates against a FHIR server, fetches a patient's vital signs, and renders interactive charts — heart rate, blood pressure, SpO2, temperature, weight, and BMI. The whole thing fits in a single index.html file. No React, no bundler, no npm install. Just a text editor and a browser.

By the end you'll have a working app and a mental model for how every SMART on FHIR app works under the hood — whether it's a one-page demo or a production clinical decision support tool launching inside Epic.

Prerequisites

You need two things:

1. A mock.health account. Go to mock.health and sign up. It's free. This gives you a FHIR R4 server with synthetic patients that actually have realistic clinical data — vital signs, conditions, medications, imaging studies.

2. A registered SMART app. In the mock.health dashboard, go to Sandbox → Register App and create a new app with these settings:

App Name: Vital Signs Chart (or whatever you want)
Redirect URI: http://localhost:8080/smart-on-fhir-vital-signs/index.html
Scopes: launch/patient, patient/Patient.rs, patient/Observation.rs, openid, fhirUser

Copy the Client ID — you'll need it in a minute.

A note on scope syntax. SMART App Launch STU2 introduced a new scope format. The v1 format patient/Patient.read became patient/Patient.rs in v2, where the suffix letters map to individual operations: create, read, update, delete, search. So .rs means read + search, and v1's .write maps to v2's .cud. Servers advertise which format they support via permission-v1 and permission-v2 in their capabilities. Most production EHRs accept both formats today. This tutorial uses v2 (*.rs), but v1 (*.read) will also work with mock.health.

The redirect URI matters. It must exactly match the URL where your app is running. When the authorization server sends the user back to your app after login, it appends an authorization code to this URL. If it doesn't match what you registered, the server rejects the request.

Step 1: Discover the SMART Endpoints

Every SMART-enabled FHIR server publishes a discovery document at /.well-known/smart-configuration. This tells your app where to send the user for authorization and where to exchange codes for tokens.

const baseUrl = 'https://api.mock.health';

const response = await fetch(`${baseUrl}/fhir/.well-known/smart-configuration`);
const config = await response.json();

// config.authorization_endpoint → where to redirect the user
// config.token_endpoint         → where to exchange the code for a token

The response looks like this:

{
  "issuer": "https://api.mock.health",
  "authorization_endpoint": "https://api.mock.health/smart/authorize",
  "token_endpoint": "https://api.mock.health/smart/token",
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["launch/patient", "patient/Patient.rs", "patient/Observation.rs", "openid", "fhirUser"],
  "capabilities": ["launch-standalone", "client-public", "context-standalone-patient", "permission-v1", "permission-v2", "sso-openid-connect"]
}

Why discovery instead of hardcoding? Because every FHIR server puts these endpoints at different paths. Epic uses /oauth2/authorize. Oracle Health (Cerner) uses /tenants/{tenant}/protocols/oauth2/profiles/smart-v1/personas/patient/authorize. The discovery document means your app works against any conformant server without code changes.

Step 2: Generate a PKCE Challenge

PKCE (Proof Key for Code Exchange, pronounced "pixie") prevents authorization code interception attacks. Your app generates a random secret (the verifier), hashes it (the challenge), and sends only the hash to the authorization server. When you exchange the code for a token later, you prove you're the same app by sending the original verifier.

function generateCodeVerifier(len = 64) {
  const arr = new Uint8Array(len);
  crypto.getRandomValues(arr);
  return base64url(arr);
}

async function computeCodeChallenge(verifier) {
  const digest = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(verifier)
  );
  return base64url(new Uint8Array(digest));
}

function base64url(bytes) {
  let bin = '';
  for (const b of bytes) bin += String.fromCharCode(b);
  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

Store the verifier in sessionStorage — you'll need it after the redirect.

const verifier = generateCodeVerifier();
const challenge = await computeCodeChallenge(verifier);
sessionStorage.setItem('pkce_verifier', verifier);

Step 3: Redirect to Authorize

Build the authorization URL and redirect the user's browser:

const state = crypto.randomUUID();
sessionStorage.setItem('auth_state', state);

const params = new URLSearchParams({
  response_type: 'code',
  client_id: clientId,
  redirect_uri: location.origin + location.pathname,
  scope: 'launch/patient patient/Patient.rs patient/Observation.rs openid fhirUser',
  state,
  aud: `${baseUrl}/fhir`,
  code_challenge: challenge,
  code_challenge_method: 'S256',
});

location.href = `${config.authorization_endpoint}?${params}`;

What each parameter does:

response_type: 'code' — We want an authorization code. Always code.
client_id — Identifies your app.
redirect_uri — Where to send the user back. Must exactly match what you registered.
scope — What data you're requesting. launch/patient asks for a patient context. patient/Observation.rs asks to read and search Observations scoped to that patient.
state — A random string to prevent CSRF attacks.
aud — The FHIR endpoint this token should work with. Prevents token replay across servers.
code_challenge — The PKCE challenge.

After this redirect, the user sees a consent screen. When they approve, the server redirects back to your redirect_uri with ?code=...&state=... appended.

Step 4: Handle the Callback and Exchange the Code

When your page loads, check if there's a code parameter in the URL:

const params = new URLSearchParams(location.search);
const code = params.get('code');
const state = params.get('state');

if (code) {
  if (state !== sessionStorage.getItem('auth_state')) {
    throw new Error('State mismatch — possible CSRF');
  }

  history.replaceState(null, '', location.pathname);

  const verifier = sessionStorage.getItem('pkce_verifier');

  const body = new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    redirect_uri: location.origin + location.pathname,
    client_id: clientId,
  });
  if (verifier) body.set('code_verifier', verifier);

  const response = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body,
  });

  const tokens = await response.json();
}

The token response includes everything you need:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "launch/patient patient/Patient.rs patient/Observation.rs openid fhirUser",
  "patient": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "id_token": "eyJhbGciOiJSUzI1NiJ9..."
}

Two SMART-specific fields: patient is the launch context — the ID of the patient the user selected. id_token contains the authenticated user's identity via the fhirUser claim.

Step 5: Fetch Vital Signs

Now you have a bearer token and a patient ID:

const headers = {
  Authorization: `Bearer ${tokens.access_token}`,
  Accept: 'application/fhir+json',
};

const patient = await fetch(`${baseUrl}/fhir/Patient/${tokens.patient}`, { headers })
  .then(r => r.json());

const observations = await fetch(
  `${baseUrl}/fhir/Observation?patient=${tokens.patient}&category=vital-signs&_sort=-date&_count=200`,
  { headers }
).then(r => r.json());

Each Observation has a LOINC code that identifies what it measures:

Vital Sign	LOINC Code	Value Location
Heart Rate	`8867-4`	`valueQuantity.value`
Blood Pressure	`85354-9`	`component[].valueQuantity.value`
Temperature	`8310-5`	`valueQuantity.value`
SpO2	`2708-6`	`valueQuantity.value`
Weight	`29463-7`	`valueQuantity.value`
BMI	`39156-5`	`valueQuantity.value`

Blood pressure is the odd one out. It's a panel — the Observation itself has LOINC code 85354-9, but the actual systolic and diastolic values live in component entries with their own LOINC codes (8480-6 for systolic, 8462-4 for diastolic). Every FHIR developer hits this for the first time and wonders why it's nested. Welcome to the club.

Step 6: Render the Charts

We use Chart.js — one CDN script tag, no build step:

<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>

Group observations by type, sort by date, render a line chart for each. For blood pressure, render two datasets on the same chart — systolic and diastolic.

The Complete App

The full working app is ~475 lines in a single index.html. Clone it and run it:

git clone https://github.com/mock-health/samples.git
cd samples
python3 -m http.server 8080

# Open http://localhost:8080/smart-on-fhir-vital-signs/index.html

Enter your Client ID, click Connect, approve access, and you'll see your patient's vital signs charted out.

The full source is on GitHub.

What Changes in Production EHRs

This tutorial uses mock.health, which implements the SMART spec faithfully. Production EHRs are different:

App registration takes weeks, not seconds. Epic's App Orchard requires a formal review process. Budget 2–8 weeks for approval.

Scopes vary. Some EHRs still only accept v1 syntax (patient/Observation.read). Check the server's .well-known/smart-configuration capabilities.

Discovery endpoints aren't always where you expect. Some older servers don't support .well-known/smart-configuration. Fall back to the CapabilityStatement (GET /metadata) and extract OAuth URLs from rest[0].security.extension.

Tokens expire and refresh tokens matter. In production, request offline_access scope and implement refresh token rotation.

None of this changes the fundamental flow. Discovery → PKCE → authorize → callback → token → API calls. Same everywhere. The operational details differ.

Sign up at mock.health — free tier, no sales call. The hardest part of building a SMART on FHIR app is getting access to a server that has realistic data and implements the spec correctly. Now you have one.

The FHIR Sandbox Problem: Why Open Epic Won't Get You to Your First Customer

mock health — Sun, 22 Mar 2026 21:05:56 +0000

You're three months into building a FHIR integration. You've got OAuth working, you can pull Patient resources, your UI renders demographics cleanly. Time to show it to a potential customer.

You open the sandbox patient and see this:

{
  "resourceType": "Patient",
  "id": "erXuFYUfucBZaryVksYEcMg3",
  "name": [
    {
      "use": "usual",
      "text": "Test Cancer",
      "family": "Cancer",
      "given": ["Test"]
    }
  ],
  "birthDate": "1971-08-07",
  "gender": "female",
  "address": [
    {
      "use": "home",
      "line": ["123 Main St."],
      "city": "Madison",
      "state": "WI",
      "postalCode": "53703"
    }
  ]
}

The patient's name is "Test Cancer." The address is 123 Main St. There are no emergency contacts, no marital status, no communication preferences. You scroll through the rest of the sandbox patients. "Derrick Lin." "Jason Argonaut." A handful of others, all equally sparse.

This is Open Epic's sandbox. And it's the starting point for nearly every FHIR startup in the US.

What Open Epic Actually Gives You

Open Epic provides a shared FHIR R4 sandbox with eight named test patients (Camila Lopez, Derrick Lin, Desiree Powell, Elijah Davis, Linda Ross, Olivia Roberts, Warren McGinnis, and Jason Argonaut). These patients exist to validate API connectivity — to confirm that your OAuth flow works, that you can parse a Bundle, that your FHIR client handles pagination. They were never designed to represent what real patient data looks like.

Here's what the sandbox gives you versus what you need to demo a real clinical application:

Capability	Open Epic Sandbox	Production Demo Needs
Patient demographics	Name, DOB, gender, address	Race, ethnicity, language, multiple addresses, contacts
Conditions	1-3 active conditions	5-15 conditions with onset dates, comorbidity patterns
Medications	Sparse, often missing	Active + historical, with dosage and frequency
Lab observations	Few, no trends	Longitudinal panels (HbA1c over 3 years, lipid trends)
Imaging studies	None	ImagingStudy + DiagnosticReport with narrative text
Clinical notes	None or minimal	Discharge summaries, progress notes, radiology reports
Encounters	1-3 encounters	Multi-year history across ambulatory, inpatient, ED
Vital signs	Sparse	Trending data (BP, weight, heart rate over time)

The sandbox is optimized for certification. It proves your app can authenticate and read FHIR resources. It says nothing about whether your app can handle a real patient record.

The Alternative Landscape Is Shrinking

Open Epic isn't the only sandbox, but the options are thinner than you'd think.

Logica Health (formerly HSPC) ran a well-regarded public sandbox for years. It was retired on October 31, 2024. If your integration documentation still points there, those links are dead.

SMART Health IT maintains a sandbox with about 100 Synthea-generated patients. The data is structurally valid but clinically shallow — default Synthea output without enrichment. (If you've used it, you know the feeling: the FHIR parses fine, but the patient has three conditions and no meds.)

Individual health systems sometimes provide sandbox access, but getting it requires a signed BAA, a security review, and months of procurement. That's not a sandbox. That's a sales cycle.

The Gap Between Sandbox and Production

Missing fields are the obvious problem. The deeper problem is missing clinical coherence — real patient data tells a story, and sandbox data doesn't have one.

No Comorbidities

In the real world, Type 2 Diabetes doesn't travel alone. It shows up with hypertension, hyperlipidemia, chronic kidney disease, and obesity. A 62-year-old diabetic in a production EHR typically has 8-15 active conditions, most of them clinically related.

Open Epic's test patients have conditions, but they're isolated. You won't find a patient whose diabetes diagnosis is followed by quarterly HbA1c labs trending from 7.2 to 8.1 over 18 months, with a metformin prescription added at diagnosis and a GLP-1 agonist added when the HbA1c crossed 8.0. That's what your app needs to demo against.

No Imaging, No Clinical Narrative

Search for ImagingStudy resources in the Open Epic sandbox. Empty bundles. No DiagnosticReports with radiology narrative. No discharge summaries, no progress notes. Production EHRs have presentedForm.data fields with base64-encoded report text — the full narrative a radiologist dictated. Sandboxes have "FINDINGS: Normal. IMPRESSION: Normal." or nothing at all.

If you're building anything that touches imaging, clinical NLP, or document summarization — you have zero test data to work with.

No Longitudinal History

Real patients have years of history. A production Patient sits at the center of hundreds of linked resources — encounters spanning a decade, medication changes over time, lab trends that tell a clinical story.

Sandbox patients have one or two encounters. You can't demonstrate a timeline view, trend analysis, or care gap detection when the patient's entire history fits in a single API response.

What You Actually Get: Epic Sandbox vs. Production

To make this concrete, here's a real query against the Epic on FHIR sandbox for Camila Lopez — the "Test Cancer" patient from the opening of this post — filtering for laboratory observations:

curl -s "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/Observation\
?patient=erXuFYUfucBZaryVksYEcMg3&category=laboratory" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/fhir+json" | jq '.total, [.entry[].resource |
    {code: .code.text, date: .effectiveDateTime,
     value: (.valueQuantity.value | tostring) + " " + .valueQuantity.unit}]'

A representative sandbox response:

2,
[
  {
    "code": "Hemoglobin A1c/Hemoglobin.total in Blood",
    "date": "2019-06-10T15:38:00Z",
    "value": "7.6 %"
  },
  {
    "code": "Glucose [Mass/volume] in Blood",
    "date": "2019-06-10T15:38:00Z",
    "value": "138 mg/dL"
  }
]

Two observations. Both from the same date. No prior values, no subsequent values. If you're building a diabetes management dashboard, a trend chart, or a care gap detector — this tells you nothing.

Now compare that to what a production EHR returns — or what mock.health generates — for a 62-year-old with Type 2 Diabetes:

15,
[
  { "code": "Hemoglobin A1c", "date": "2022-01-15", "value": "6.8 %" },
  { "code": "Hemoglobin A1c", "date": "2022-04-22", "value": "7.1 %" },
  { "code": "Hemoglobin A1c", "date": "2022-07-30", "value": "7.4 %" },
  { "code": "Hemoglobin A1c", "date": "2022-10-18", "value": "7.9 %" },
  { "code": "Hemoglobin A1c", "date": "2023-01-12", "value": "8.1 %" },
  { "code": "Hemoglobin A1c", "date": "2023-04-05", "value": "7.6 %" },
  { "code": "Hemoglobin A1c", "date": "2023-07-20", "value": "7.3 %" },
  { "code": "Hemoglobin A1c", "date": "2023-10-11", "value": "7.1 %" },
  { "code": "Hemoglobin A1c", "date": "2024-01-08", "value": "7.0 %" },
  { "code": "Hemoglobin A1c", "date": "2024-04-15", "value": "6.9 %" },
  { "code": "Glucose",        "date": "2022-01-15", "value": "128 mg/dL" },
  { "code": "Glucose",        "date": "2022-07-30", "value": "156 mg/dL" },
  { "code": "Glucose",        "date": "2023-01-12", "value": "172 mg/dL" },
  { "code": "Glucose",        "date": "2023-07-20", "value": "145 mg/dL" },
  { "code": "Glucose",        "date": "2024-04-15", "value": "132 mg/dL" }
]

Fifteen observations spanning two and a half years. You can see the HbA1c climbing from 6.8 to 8.1 — the point at which a clinician would escalate medication — then trending back down after treatment adjustment. The glucose values correlate. There's a clinical story in this data.

The sandbox has the right resource types. The data inside them is empty.

What "Realistic" Means for a FHIR Integration

"Realistic" has a specific definition. It's in the spec.

US Core Profiles

US Core is the implementation guide that specifies how FHIR resources should be structured in the US healthcare system. Every EHR certified under ONC's Health IT Certification Program must conform to US Core profiles.

US Core doesn't just say "include a Patient resource." It specifies which fields are required (must be present), which are must-support (must be handled if present), and which extensions are standard. A US Core Patient requires name, gender, and identifier. It must-supports race, ethnicity, birthDate, and communication.

If your test data doesn't include must-support fields, you can't verify that your app handles them correctly. And if your demo doesn't show them, your prospect — who looks at US Core-conformant data all day — will notice.

USCDI Data Classes

The United States Core Data for Interoperability (USCDI) defines the minimum data classes that certified health IT must support. USCDI v3, mandatory as of January 2026, includes:

Patient demographics (including sexual orientation and gender identity)
Allergies and intolerances
Medications (active and historical)
Problems (conditions)
Procedures
Laboratory results
Vital signs
Clinical notes (discharge summaries, progress notes, consultation notes)
Diagnostic imaging (reports and studies)
Health insurance information
Clinical tests

Your test data should cover all of these. The sandbox covers maybe four.

Correlated Clinical Data

The hardest gap to fill is missing correlations. In real clinical data, conditions, medications, labs, and encounters are causally connected. A diabetes diagnosis triggers HbA1c monitoring every 3-6 months. An elevated creatinine prompts a nephrology referral. An abnormal chest X-ray leads to a CT follow-up.

Standard synthetic data generators don't model these relationships. A 2019 validation study of Synthea in BMC Medical Informatics and Decision Making found that Synthea-generated populations showed 0% blood pressure control rates compared to 69.7% in real-world data. The resources parse. The population statistics are wrong.

Try It

You can query mock.health's FHIR API directly:

curl -s https://api.mock.health/fhir/Patient?_count=1 \
  -H "Accept: application/fhir+json" | jq '.entry[0].resource | {
    name: .name[0].text,
    birthDate,
    gender,
    race: .extension[] | select(.url | contains("race")) | .extension[0].valueCoding.display,
    ethnicity: .extension[] | select(.url | contains("ethnicity")) | .extension[0].valueCoding.display
  }'

And a radiology report with actual clinical narrative:

curl -s "https://api.mock.health/fhir/DiagnosticReport?category=RAD&_count=1" \
  -H "Accept: application/fhir+json" | jq -r '
    .entry[0].resource.presentedForm[0].data' | base64 -d

That base64 -d decodes the report text. You'll see findings, impressions, and clinical language — not "Normal. Normal. Normal."

If you've already built a SMART on FHIR app, you can point it at https://api.mock.health/fhir and get realistic clinical data through the same OAuth flow you'll use in production.