Case study · FHIR CRD Router and Payer Onboarding Workbench
Keep the directory separate from the patient data.
A Java library that maps an insurer’s ID to the right CRD connection and never touches patient data. A companion workbench onboards a payer connection and, when it fails, says which check failed and how to fix it.
Java 17 / 21
CDS Hooks
OAuth2 / JWT
Mutual TLS
Spring Boot
Who it’s for
Provider organizations that have to reach many insurers’ CRD endpoints. CRD (Coverage Requirements Discovery) is the CDS Hooks workflow where an insurer tells the clinician, at order time, whether something like prior authorization is needed.
The workbench is for whoever brings a new payer connection online and has to work out why it doesn’t work yet.
The problem
Hospitals and clinics have to check with each insurer’s system before certain orders. Every insurer runs its own endpoint, so finding the right one is a mess.
New federal interoperability requirements are pushing payers to stand up CRD endpoints. Each one is another connection to manage on top of the EDI connections we already run: batch file exchanges and real-time ones like eligibility inquiries. Running those connections day to day is labor-intensive, and the legacy process makes it hard to see which connections exist.
Finding the endpoint is only half of it. A new connection can fail at discovery, at authentication, at the hook call or in the response, and the error a payer sends back rarely says which.
Constraints
No patient data in the directory. An organization should be able to adopt it without sending PHI to code outside its own walls.
No secrets on the record. A connection record holds only opaque references into a credential provider, never a secret.
Every payer authenticates its own way. An API key, OAuth2 client credentials, an RFC 7523 signed client assertion as in SMART Backend Services, or the CDS Hooks 2.0 client JWT, and some also require mutual TLS.
Payers don’t all follow the spec to the letter. The HL7 Da Vinci CRD reference implementation uses its own prefetch keys, returns coverage information inside card suggestions rather than systemActions, and uses an older extension shape.
A library first. Java 17 as the baseline, no HAPI FHIR dependency, and nothing that has to be hosted.
Synthetic data only. No real payer, patient or PHI anywhere in either repo.
Decisions and tradeoffs What was chosen, what was passed on, and what it costs
Discovery only
Chose
The core resolves a payer ID to a connection record and never touches patient data. Credentials sit behind a pluggable provider interface, so each organization decides where secrets live and which connections it supports. Only the optional client SDK talks to a payer.
Passed on
An all-in-one solution that also collects and maintains the connections.
Cost
Organizations still have to collect and maintain their own connection records. The library gives that work a clear structure but doesn’t do it for them.
Mutual TLS is a transport setting, not an auth type
Chose
An optional mtlsCredentialRef on the record. A record that has one gets its own TLS 1.2+ client, combinable with any auth type, because CDS Hooks describes mutual TLS as used alongside JWTs and a payer may require mutual TLS plus OAuth.
Passed on
A MUTUAL_TLS value in the auth-type enum, which would have made it one or the other.
Cost
It changed the record schema fixed in the original scoping session. Nothing was published yet, so no one had to migrate.
FHIR resources stay as JSON
Chose
Typed models for all six CRD hooks, prefetch keys, cards and coverage information, with the FHIR resources inside them kept as Jackson JsonNodes to keep the library light.
Passed on
A HAPI FHIR dependency. It could come back later as an optional adapter module.
Cost
Typed contexts don’t validate against full FHIR profiles, and FHIR resources are untyped.
Diagnostics see JWT claims, never secrets
Chose
The workbench redacts headers, bodies and evidence when they are recorded, and again when a report is built. JWTs keep their header and payload. Only the signature is masked, because claims such as iss, aud and exp are the usual cause of token failures.
Passed on
Masking every token whole, which would hide the claim that broke the connection.
Cost
Claims appear in reports. A JWT that is the value of a secret field such as access_token, or a bearer credential, is still masked whole.
Recorded runs on the site, not a live app
Chose
The workbench exports a replay bundle: real runs recorded against the synthetic payers, plus a small viewer with no framework and no dependencies.
Passed on
Hosting the Java app, which a static site can’t do.
Cost
Visitors replay fixed scenarios rather than running their own, and the bundle has to be re-exported and re-vendored whenever the workbench changes.
How it was built
directory-core · never sees patient data
ConnectionStoreconnection records in a flat YAML file by default
PayerRouterpayer ID → ConnectionRecord
CredentialProviderresolves the record’s references; an AES-GCM encrypted local file by default
client-sdk · optional, the only part that calls a payer
CdsHooksClientdiscovery, authentication, then the hook call
Payer’s CRD endpoint CDS Hooks GET /cds-services and the named hook
payer-onboarding-workbench · a run, step by step
Resolve connection
Discovery
Authenticate
Send the sample hook request
Parse the response
Run diagnostics
The router’s modules, top to bottom in the order a call uses them, and the six steps of a workbench run. The first failing step stops the run, and diagnostics run on whatever was observed.
The router
Four Maven modules: directory-core (the record model, the store and credential interfaces, and the router), credential-store-encrypted-local (the default credential provider), client-sdk (the CDS Hooks client), and examples-quickstart, which loads sample records from YAML, resolves a payer, and calls an in-process mock CDS Hooks server. Tokens are cached in memory until shortly before they expire, and a 401 triggers one retry with a fresh token. JWTs are signed with RS384 or ES384, chosen from the key.
The companion workbench
A Spring Boot workbench onboards three synthetic mock payers with deliberately different auth and response behavior, and when a connection fails it says which check failed and how to fix it. All three are mocks, so this shows the diagnosis, not real-payer interoperability.
Northwind Health follows the spec: CRD 2.2.1, standard prefetch keys and OAuth2 client credentials. Fabrikam Benefits is quirky in the same ways as the HL7 reference implementation: the older CRD 2.0.1, non-standard prefetch keys, coverage information inside card suggestions, and the CDS Hooks client JWT, with aud checked against the exact service URL. Tailspin Health Plan also follows CRD 2.2.1 with standard prefetch keys, and authenticates with SMART Backend Services. Each payer has the same faults to switch on: a slow response, an expired token, a wrong audience, malformed cards, discovery down, strict prefetch, and three certificate faults. The README’s table pins each fault to the step it breaks and the check that fails, and the integration tests hold the app to that table on all three.
A finished run exports as a report in HTML, Markdown or JSON, to attach to a ticket or send to a payer: the verdict, the step where the flow broke, every HTTP exchange, and each finding with its explanation, redacted evidence and fix.
The workbench app, with one payer fault switched on for a single run. Screenshot from the workbench README.One finding from the exported report for Fabrikam’s wrong-audience fault: what happened, the evidence and the fix.
Where AI agents did the work, and what I decided
AI coding agents implemented most of the work in both repos: 10 of the router’s 13 non-merge commits and 48 of the workbench’s 52 carry a Claude co-author line. I decided the scope and the design, and I merged every pull request.
The router’s architecture was fixed in a scoping session before any code. The agent proposed defaults for what that session left open (name, Java baseline, build tool, record storage); I confirmed them and changed one, the group ID, to match my GitHub account.
The auth and mutual TLS design, including mutual TLS as a transport setting and the two JWT auth types, was my choice on each point when the agent asked.
Each workbench decision is written down with its rationale so I can override it, and changing one means a new issue, not a silent edit. The modules were laid out one per issue so three workers could build in parallel without editing the same files.
What’s proven so far
Results
The router builds and passes 697 tests in CI on Java 17 and 21 (Linux, 30 October 2026). 16 more run against the HL7 Da Vinci CRD reference implementation at a pinned commit in the same CI, and a weekly workflow repeats them against that project’s latest code, last passing on 26 October 2026.
The quickstart runs end to end against an in-process mock CDS Hooks server with synthetic connection records.
The workbench’s CI runs its tests, then a demo tour that fails if an expected finding is missing, then the replay export and a leak scan of the bundle.
Limits
Not yet tried against a real payer sandbox.
The workbench’s payers are mocks.
The router isn’t published to Maven Central yet.
The recorded runs on this site come from before the workbench added its certificate faults.
Next
Test against a real payer sandbox.
Add notifications for credentials that are close to expiring or that fail authentication.
Publish the router to Maven Central.
Try it
Try it Watch a payer connection break, and see why
Routing a request to the right partner is half the job. The other half is working out why a new connection fails. These are recorded runs of the payer onboarding workbench against two of its three synthetic payers, both healthy and with faults injected on purpose. Pick a scenario to replay its steps, then see the failing check and the suggested fix.
Recorded run against a synthetic mock payer. Passing here does not prove real-payer interoperability.