Skip to main content

Enroll and verify agent identity

Design-stage

Identity enrollment is designed (docs/phases/phase-4-transaction-tokens-taint-identity.md, FR-15/16/17) but not yet implemented — there is no /v1/agents/{id}/enroll route in this codebase today. The steps below describe the intended flow.

Goal (designed): prove an agent holds the private key it claims to, bind it to an accountable human or organizational principal, and get an offline-verifiable identity a resource server can check without a network call.

1. Present an identity document​

The agent (or its operator, on its behalf) presents an identity document — OIDC claims plus a JWKS exposing its public key — to POST /v1/agents/{id}/enroll.

2. Answer the challenge​

The control plane issues a nonce. The agent signs it with its private key and returns the signed response. The control plane verifies the signature against the presented public key — this is the proof-of-possession step: it confirms the agent holds the key it claims to, not just that it can name one.

3. Bind to an accountable principal​

Enrollment federates to your organization's human IdP (OIDC) to confirm the agent acts on behalf of a real, accountable person or org. No binding, no enrollment: an agent that can't be tied to an accountable principal is quarantined, not admitted.

4. On success, a trust anchor is pinned​

A successful enrollment (plus a reconciled manifest, from registering and reconciling a manifest) pins a trust anchor: key + manifest version + principal, at a specific version. This is what the offline verifier checks against at runtime — no round-trip to the control plane needed per call.

5. Verify offline at runtime​

A resource server (typically a boundary adapter in resource-server mode) checks the agent's self-signed identity against the pinned JWKS with no network call. Once identity enforcement is deployed, a resource server admits a call only with both a valid identity and a valid scoped grant — identity alone is never sufficient, and neither is a grant alone.

6. Revoke when needed​

POST /v1/agents/{id}/revoke invalidates the trust anchor immediately, along with every delegation chain built on it — not just future calls from that agent, but the authority it had already extended to anything downstream.