Public Reference Implementation
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.
src/agent_identity.py (26 dedicated tests). Open for production use under the open license. 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 (current) | v2 (reference implementation) |
|---|---|---|
| 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 |
| Maturity | Shadow-pilot ready | Early testing only |
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.
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
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.
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.