Skip to main content

ADR-006: Agent Identity and Authentication

Status: Accepted Date: 2026-03-20

Context​

Agents query the trust authority to retrieve trust signals. The authority needs to know who is asking — for rate limiting, audit trails, and accountability.

The ideas.md specifies that agent identity uses a did:web identifier carried as a JWT header.

Decision​

Use DID-based identity. Agents MAY present a did:web Decentralized Identifier as a signed JWT in the Authorization header to identify themselves to the trust authority. Agent identification is optional per-request — authorities MUST NOT gate access on identity.

How It Works​

  1. The agent operator gets certified by a identity authority supporting the Trust Signals for Agent Interactions Protocol (TSAI)
  2. The agent operator hosts a DID Document at their domain (per the did:web method specification)
  3. The DID Document contains the agent's public key
  4. For each request, the agent creates a JWT signed with its private key
  5. The JWT includes the did:web identifier as the iss (issuer) claim
  6. The agent sends the JWT in the Authorization: Bearer <jwt> header
  7. The trust authority resolves the did:web to the DID Document, retrieves the public key, and verifies the JWT signature

JWT Claims​

{
  "iss": "did:web:agent.example.org",
  "iat": 1711000000,
  "exp": 1711003600,
  "aud": "authority.example.org"
}
ClaimDescription
issThe agent's did:web identifier
iatToken issued-at timestamp
expToken expiration (short-lived, recommended 1 hour)
audThe trust authority's domain

Implementation Details​

The did:web method and JWT mechanics are defined by the TSAI protocol. Agent identification is optional per-request — agents MAY present a did:web JWT in the Authorization header, and authorities MUST NOT gate access on identification. The mechanics of DID resolution and JWT verification follow the TSAI specification.

Authority Behavior​

  • Authorities MUST accept requests without an Authorization header — identification is never a prerequisite
  • When a JWT is presented, authorities MUST validate it; a rejected JWT returns 401 Unauthorized. A missing JWT MUST NOT return 401.
  • The authority SHOULD log the agent's did:web identifier on each identified response (audit trail)
  • The authority MAY enforce rate limits using an implementation-defined strategy
  • The authority MAY maintain an allowlist of accepted agent identities

Options Considered​

A. Anonymous access. No agent identification. Zero friction. The authority cannot rate-limit, audit, or hold agents accountable. Abuse risk is high in an automated environment where agents make rapid queries.

B. API key. Agents register and receive a key. Simple. Requires centralized registration — the authority must manage key issuance. Ties agents to the authority's registration system.

C. DID-based identity (chosen). Self-sovereign — agents control their own identity by hosting a DID Document. Cryptographic proof of identity. No centralized registration required. Ties identity to a domain the operator controls (via did:web). Aligns with the TSAI protocol's identity layer.

D. Tiered (anonymous read, authenticated write). Reading is open; writing requires authentication. Reduces friction for read-only agents. Two authentication paths to specify and maintain. Given that the authority logs all interactions for the audit trail, anonymous reads would create gaps in the log.

Consequences​

  • Agents can query all authorities without a did:web identity — identification is never required
  • Agents that have a did:web identity MAY present it; authorities MAY use it for logging, rate-limit tuning, or response tailoring (all implementation-defined)
  • The authority does not manage agent registration — identity is self-sovereign
  • The audit trail is complete for identified requests; unidentified requests have no cryptographic agent identity to log
  • Rate limiting strategy is implementation-defined
  • A future revision may introduce access gates under a deliberately chosen framing — see the roadmap

References​

  • ADR-002 — Verification Endpoint Schema (request format)
  • ADR-005 — Trust Authority Model (authority behavior)
  • context/threat-model.md — T8: Sybil Attacks (DID-based identity mitigates)
  • W3C DID Core Specification
  • did:web Method Specification
  • TSAI protocol — JWT mechanics, DID resolution, agent identity certification