Open governance framework · v1.3 · Practitioner-led · not an accredited standard, certification, or regulatory requirement · seeking shadow-evaluation partners
Home/Framework/NHID-Auth

Layer 3 · v2 · CC BY 4.0

NHID-Auth

v1.3 tells you the caller was automated. NHID-Auth tells you the caller was authorized.

The gap it closes

NPIs are public. A caller can state one truthfully and still have no relationship to the organization it names. Behavioral controls establish that a caller disclosed itself as automated; they cannot establish that it was ever delegated authority to act for the provider it claims.

NHID-Auth addresses that with signed delegation rather than a registry or a gatekeeper. A provider signs a statement binding an agent’s public key to an NPI and a bounded scope. The receiving side verifies that signature offline — no lookup, no central authority, no service to call.

How it works

  1. 1Provider signs a delegationThe provider organization holds a key pair and signs a passport binding an agent public key to its NPI, a purpose, a scope, and an expiration.
  2. 2Agent presents the passportThe AI agent carries the signed passport into the call alongside its behavioral disclosure.
  3. 3Receiver verifies offlineEd25519 signature verification against the provider’s published public key. No network call to NHID-Clinical, no registry lookup, no dependency on us.
  4. 4Scope is enforcedAn agent delegated for eligibility checks cannot use the same passport to pursue claims appeals. Scope is a precondition, not a suggestion.
  5. 5Expiration and revocationPassports carry an expiry. A provider revokes by rotating keys or publishing a revocation, without coordinating with any third party.

Design properties

No registry, no gatekeeper

Verification is a signature check. NHID-Clinical is not in the trust path and cannot become a chokepoint.

Offline verifiable

Works when the network does not. Nothing about verification requires reaching an external service in real time.

Bounded by construction

Scope and expiration are fields in the signed payload, so an over-broad or stale passport fails verification rather than relying on policy.

Open reference code

The implementation is public in the repository under CC BY 4.0. Fork it, port it, or write your own against the format.

ⓘ Status: NHID-Auth v2 is a published open reference implementation, not a deployed identity infrastructure. There are no production issuers yet. It documents a workable approach to delegated agent authority and invites implementers to break it.

Work with NHID-Auth

The reference code, the integration notes, and the layer it sits in.

Reference implementation →Where the code lives and how to run it. The five-layer stack →How Layer 3 relates to the rest. Developer guide →APIs, schemas, and integration.

NHID-Clinical is a voluntary open framework — not an accredited standard, certification, or regulatory requirement. Everything on this page is published under CC BY 4.0.

NHID-Auth v2: cryptographic agent identity

v1.3 establishes behavioral disclosure. v2 addresses what v1.3 cannot: verifying that an AI agent is actually authorized by the provider it claims to represent. NPIs are public via NPPES — any caller can present a real one. v2 makes that insufficient.

Status: Released June 2026 under CC BY 4.0. Reference implementation in src/agent_identity.py (26 dedicated tests). The licence permits any use; the maturity does not. This is a reference implementation for technical exploration and review — not independently security audited, with no production issuers, and not a substitute for an organisation’s own identity and access controls. As of v1.3 final, this is also wired into the hosted conformance API — not just a standalone library — via POST /v1/identity/verify-passport and POST /v1/identity/revoke-passport, with durable revocation that survives across stateless invocations.

Where v1.3 Ends and v2 Begins

Capability v1.3 Implemented v2 Reference
Identity disclosure ✅ Behavioral (spoken) ✅ + Cryptographic (signed)
Provider authorization ❌ Not verifiable ✅ Cryptographically verifiable
Revocation ❌ Not supported ✅ Real-time access controls
Audit trail ✅ Structured event logs ✅ + Credential ID in every log
Revocation durability — In‑memory only Reference
Key custody, rotation, tenant isolation — Documented, not built Conceptual
Registry (NPI → public key) — Does not exist Future
Standing Shadow‑evaluation ready Implemented Working primitive, not deployed infrastructure Reference

A tick in the v2 column means the reference implementation does this and the suite covers it. It does not mean the capability is deployed, operated, or available as a service. The last four rows are the ones that decide whether v2 could be run in production today, and three of them are Conceptual or Future. Standings follow claim-boundaries.md.

Where v2 Sits in the Trust Stack

v2 is one layer in a stack that starts at a real gap (no cross-org NPI authorization exists today) and ends at a healthcare-native audit trail. Layers 2–4 are NHID-Clinical's contribution; Layer 3 (this page) is optional.

The five-layer trust stack, in cross-section Five layers, drawn bottom to top. Layer 1, STIR/SHAKEN, authenticates the carrier number and emits an attestation on the call leg. Layer 2, NHID-Clinical v1.3, is this framework: it establishes the behavioural disclosure baseline and emits a PolicyDecision with a reason code. Layer 3, NHID-Auth v2, is an optional extension adding cryptographic authorization through a signed agent passport. Layer 4, FHIR AuditEvent R4, emits an audit bundle per turn. Layer 5, OpenTelemetry, carries traces, spans and latency. Beneath all five sits layer 0, the NPI gap: no cross-organization authorization exists for AI agents today, which is the problem the stack is assembled to address. Only layer 2 is NHID-Clinical itself; layer 3 is its optional extension and the rest are existing standards it emits into. CONTROL PURPOSE EVIDENCE EMITTED 5 OpenTelemetry Observability & metrics Traces, spans, latency 4 FHIR AuditEvent R4 Audit logging AuditEvent bundle per turn 3 NHID-Auth v2 Cryptographic authorization Signed agent passport 2 NHID-Clinical v1.3 Behavioural disclosure baseline PolicyDecision + reason code 1 STIR/SHAKEN Carrier number authentication Attestation on the call leg 0 The NPI gap — no cross-organization authorization for AI agents ■ NHID-Clinical v1.3 · ■ NHID-Auth v2, optional extension · ■ existing standards this stack emits into

Reference Architectural model of how the layers relate. Layer 2 is specified and implemented in this repository; layer 3 is released as a separate document; layers 1, 4 and 5 are existing standards and are not provided by NHID-Clinical.

What the Reference Implementation Contains

Provider-Issued Agent Credentials

An agent's identity is signed by the provider organization it acts for, with the provider's 10-digit NPI bound into the credential. A valid credential requires the provider's private key — something public NPI data cannot produce.

Scoped, Time-Limited Authorization

Agents carry only the operations their provider granted (eligibility, claim status, prior authorization). Credentials expire on a short TTL. Delegation can be narrowed, never expanded — scope escalation is rejected at verification.

Immediate Withdrawal

A provider can revoke a compromised or decommissioned agent; the next verification fails. Revocation works per-agent or per-delegation. No central authority required.

Call Binding and Out-of-Band Verification

Credentials can be bound to a specific call session, preventing replay across calls. All checks happen via API, not in the voice channel — no latency added to the call. v1.3 behavioral controls run unchanged alongside the v2 layer.

How the Credential Flow Works

The NHID-Auth v2 credential chain, end to end Four ordered steps. One: the provider organization signs the agent’s public key with its Ed25519 issuing key, binding its NPI, the granted scopes and a short expiry into the credential. Two, optional: the credential may be delegated down a chain of at most three hops, and scope can only narrow — any attempt to widen it is rejected at verification. Three: the agent presents its passport out of band via API, with a nonce bound to the specific call SID so it cannot be replayed across calls, adding no latency to the voice channel. Four: the payer side runs six ordered checks — provider signature by Ed25519, NPI binding, expiry, revocation, nonce and call-SID match, and scope containment — and then writes an audit record. CREDENTIAL CHAIN 1 Provider issues Signs the agent’s public key with its Ed25519 issuing key, binding NPI, scopes and a short expiry. 2 Scoped delegation Optional. At most 3 hops, and scope can only narrow — widening is rejected at verification. 3 Passport presented Out of band via API, with a nonce bound to the call SID. No latency added to the voice channel. 4 Payer-side verification Six ordered checks below, then an audit record is written. STEP 4 · SIX ORDERED CHECKS, THEN AN AUDIT RECORD 1. Provider signature (Ed25519) 2. NPI binding 3. Expiry 4. Revocation 5. Nonce / call-SID match 6. Scope containment

Reference Protocol model from the NHID-Auth v2 document. NHID-Auth v2 is a separate release from the v1.3 behavioural baseline, and is optional.

Run It

git clone https://github.com/NHID-Clinical/NHID-Clinical.git
cd NHID-Clinical
pip install -r requirements.txt
python -m pytest tests/test_identity.py -v   # v2 identity layer (26 tests)
python examples/issue_and_verify.py          # end-to-end credential walkthrough

Open Design Questions

  • No registry or discovery mechanism for provider keys — open design question
  • Credential delivery during live calls is not yet standardized
  • Shadow pilot data will inform the formal v2 specification document

The reference implementation is live. If you want to test it against your own threat model or contribute to the formal specification, contact us.

← Pilot Guide  ·  v1.3 Spec  ·  Five-layer trust architecture →

Get involved

Read the specification and share your reaction.

Whether you think it is right, wrong, incomplete, or misses the real problem — that feedback is what shapes the next version.

Read the evaluation guide →