Bottom Line Up Front

For government officials and policy makers: create a standard publication point, require participation where federal and state programs have leverage, and let directories aggregate authoritative records that organizations publish themselves.

A predictable URL such as /.well-known/ushealthregistry-configuration could allow health systems, payers, health information exchanges, public agencies, and trusted application registries to publish endpoint, trust, directory, policy, and relationship metadata in a consistent machine-readable form.

This matters because the basic discovery step - finding the correct endpoint, public key, directory, or policy artifact - still slows patient access, application onboarding, provider directory accuracy, payer-provider exchange, and public-sector health data programs.

The policy lever is straightforward: CMS, ONC, state Medicaid agencies, and grant-making programs could require a signed health care discovery document as a condition of participation, certification, procurement, or funding. The same pattern could support SMART on FHIR and FHIR endpoint discovery, public keys for signed software statements, organizational and facility relationships, provider directory pointers, payer network information, trusted application lists, Direct and PKI metadata, and HIE or TEFCA-related connection information.

A practical next step would be a federal or state pilot with health systems, payers, HIEs, patient-facing applications, and agencies to define a compact schema, publish sample .well-known documents, test signed JWT and JWKS artifacts, and measure whether onboarding and directory maintenance improve.

Introduction

The notion of discovery is present throughout modern digital systems. In this article, discovery means machine-readable documents published in known locations. This article describes common discovery patterns in use today and outlines ways the same approach could simplify health data exchange logistics.

Well-Known URLs

RFC 8615 defines the /.well-known/ path as a standard place to publish site-wide metadata. A service can place a file at a predictable location such as: 

https://example.com/.well-known/[some_data_or_service]

This simple convention is already used across identity, mobile applications, certificate issuance, security response, and health care.

  • OpenID Connect discovery: Identity providers publish /.well-known/openid-configuration so clients can find authorization endpoints, token endpoints, supported claims, and the jwks_uri needed to verify signed ID tokens.
  • OAuth authorization server metadata: RFC 8414 describes a similar discovery document for OAuth 2.0 authorization server configuration.
  • Apple Universal Links: Apple uses apple-app-site-association to connect web domains with native iOS applications.
  • ACME certificate challenges: Certificate authorities such as Let's Encrypt can validate domain control through /.well-known/acme-challenge/.
  • Security contacts: security.txt gives researchers and security teams a predictable way to find vulnerability disclosure instructions.
  • SMART on FHIR: SMART configuration can be published at /.well-known/smart-configuration, often relative to a FHIR server base URL.

FHIR Discovery

Fast Healthcare Interoperability Resources, usually called FHIR, already has a discovery pattern. A FHIR server can expose its capabilities at: 

[baseURL]/metadata

The result is a CapabilityStatement resource that describes the server, supported resources, formats, interactions, and operations. FHIR servers usually expose this metadata without requiring authentication so developers and relying systems can understand what the server supports before connecting. 

https://hapi.fhir.org/baseR4/metadata
https://hapi.fhir.org/baseR4/metadata?_format=json

This is useful, but it is only one part of the larger ecosystem. FHIR discovery can tell an application about one FHIR server. It does not, by itself, answer broader questions about organizations, facilities, payer networks, app registries, public keys, Direct addresses, or trust bundles.

Signed Documents for Discovery

JSON Web Tokens, commonly pronounced "jot," are widely used as signed machine-readable documents. A JWT can carry claims, identify the issuer, and allow a receiver to verify that the content has not been altered. When a JWT is signed but not encrypted, the contents can still be read, but tampering invalidates the signature.

Imagine Alice is an instructor for Training Inc. Widgets LLC hired Training Inc. to train its employees, and Bob works for Widgets. Training Inc. wants to communicate who took the class and what grade each employee received. Bob should not be able to record his own final grade, so Alice assembles the grade information and Training Inc. signs it.

The signed document might include a claim such as eprep_training_final_grade. If Bob received a 42, a malicious actor named Chuck should not be able to change that value to 92 without detection. Because Training Inc. signs the JWT with its private key and publishes its public keys at a jwks_uri, a relying party can verify whether the document is authentic. Training Inc could publish its public keys at a well-known URL such as: 

https://grades.training-inc.com/.well-known/certs

The same trust pattern can be applied to health care discovery documents. Public keys in a jwks_uri can originate from X.509 certificates, and signed statements can give relying parties a repeatable way to verify who said what.

Patient Access and Signed Software Statements

A software statement is a signed JWT that asserts metadata about client software. In patient access workflows, signed software statements can support dynamic client registration so a patient can use a trusted application without every provider organization re-vetting the same app by hand.

CMS already maintains a public directory of connected applications. If those entries were published as machine-readable signed statements, health systems could automate more of the application registration process while still relying on a recognizable public-sector trust signal.

Transparent Health explored this approach in the open-source Pre-OAuth Entity Trust project, and Josh Mandel has written about software statements for the Medicare app library. The idea deserves renewed attention as health care moves toward broader directory and trust infrastructure.

Discovery Documents as Directory Infrastructure

A national health care directory should answer more than "Who is this provider?" It should help people and systems understand organizations, locations, endpoints, payers, networks, policies, applications, and relationships.

A health care directory should help answer questions such as:

  • Is this provider organization covered under a given insurance plan?
  • Is this drug covered under my insurance?
  • Is this individual provider covered and accepting new patients?
  • When does provider X work at location Y?
  • Where are the electronic endpoints?
  • Where are the facilities?
  • What is the right contact information?

Electronic endpoints can include FHIR server URLs, Direct Secure Messaging information, domains, certificates, well-known URIs, and other metadata. A U.S.-specific discovery document could create a stable publication point: 

https://example.com/.well-known/ushealthregistry-configuration

The core idea is self-publication. Organizations publish their own authoritative discovery documents, and national or state systems aggregate those self-published records. This lowers the barrier to participation, reduces duplicate data entry, and avoids forcing endpoint and relationship data into registries that were not designed to manage it.

What should the layout be for this envisioned ushealthregistry-configuration endpoint? That is a good topic for a separate article, and feedback is welcome. The three pseudo-examples below illustrate the concept across a provider organization, a federal connected-app registry, and a state health information exchange.

Example 1 - A Health Provider Organization

A provider organization such as Duke Health could publish its own health registry discovery document at: 

https://dukehealth.org/.well-known/ushealthregistry-configuration

A document like this could identify the official domain, electronic endpoints, facilities, sub-organizations, accepted insurance plans, provider locations, and links to FHIR-based provider directory information.

Pseudo-example health provider organization discovery document
Pseudo-example of a health provider organization publishing a ushealthregistry-configuration document.

What the Duke Health example answers

  • What is the official domain for Duke Health? See line 3.
  • Where are the electronic endpoints published? See lines 5-12.
  • What facilities and suborganizations belong to Duke? See lines 13-14.
  • What providers are part of Duke? See lines 15-16.
  • Is an insurance plan accepted for a given facility and location? See lines 17-18.
  • Which providers work at each facility location? See line 19.
  • Where is the FHIR-based provider directory? See line 29.

Other organization types, such as insurance companies, faith-based organizations, commercial labs, and health information exchanges, could use the same document blueprint. Fields would vary by type as appropriate.

Example 2 - A Federal Connected-App Registry

A federal connected-apps registry could publish signed software statements at a known location: 

https://connected-health-registry.cms.hhs.gov/.well-known/ushealthregistry-configuration

This would let relying organizations discover vetted applications and verify signed software statements from a public registry, reducing the need to repeat the same manual registration work across every health system.

Pseudo-example federal connected-apps registry discovery document
Pseudo-example of a federal connected-apps registry publishing signed software statements.

What the CMS Connected Applications example answers

  • What apps have been vetted and digitally signed by CMS? See line 6.
  • How do I verify that CMS signed the software statement for an app? See line 5.

This can allow any CMS-aligned network to automate application registration instead of re-vetting every app.

Example 3 - A State Health Information Exchange

A state health information exchange could publish discovery metadata describing its official domain, electronic endpoints, participating organizations, outbound connections, and related network information. 

https://wvhin.org/.well-known/ushealthregistry-configuration

This kind of document could help states, health systems, and public health partners understand which organizations provide information to the exchange, which systems the exchange connects to, and where trust metadata can be found.

Pseudo-example state health information exchange discovery document
Pseudo-example of a state health information exchange publishing discovery metadata.

What the WVHIN example answers

  • What is the official domain for WVHIN? See line 3.
  • Where are the electronic endpoints published? See lines 5-10.
  • Which organizations provide information to this health information exchange? See lines 12-14, and note the use of the domain as the key.
  • What outbound systems are connected to WVHIN? See lines 15-31. TEFCA and CIVITAS are included as examples.

Conclusion

A machine-readable document at a well-known URL will not solve every health data problem, but it can solve a practical and persistent one: helping people and systems find authoritative endpoints, keys, directories, policies, applications, and relationships without custom negotiation every time.

Participation will likely require government action. The good news is that the technical pattern is simple, familiar, and proven in other parts of the internet. Discoverable documents at well-known URLs are a practical starting point for more reliable U.S. health data infrastructure.

Feedback is welcome at alan@transparenthealth.org.