Agent identity and DIDs

Agent Gateway assigns every distinct agent a deterministic W3C Decentralised Identifier (DID). The DID persists across requests and anchors every trace, metric, and policy decision to a verifiable cryptographic root of trust.

The extraction type is configured on the Identity element in the surface builder. Currently, the gateway can extract identity from request payload fields, a stored API key, or a validated JWT claim; deriving identity from a stored mTLS certificate or a fixed static DID is not yet selectable in the dashboard. Once derived, the gateway reuses the same DID for subsequent requests from the same agent, with no manual enrolment flow.

What agent identity is

Agent identity in Agent Gateway is a stable cryptographic identifier derived once and reused across all requests from the same agent. The same identity inputs always produce the same DID, so the gateway recognises the same agent consistently across requests and sessions.

Each agent identity is a did:webvh identifier anchored to the gateway’s domain:

did:webvh:z6MkScAii9T4RDvTegERUhf4esTGNQTzCgP3kfXpjBfgUA:gateway.example.com:surface:9fd06096-0188-4979-aa99-8171cde7090a

The format is did:webvh:{SCID}:{domain}:surface:{uuid}:

• {SCID}: the self-certifying identifier derived from the agent’s initial key material.
• {domain}: the gateway’s public domain.
• surface: a fixed segment that scopes agent identities within the gateway.
• {uuid}: the unique identifier of the surface that issued the identity.

did:webvh is domain-hosted and maintains a verifiable key-rotation log anchored to the gateway’s domain. Key rotations are recorded without changing the DID itself, so changes can be audited over time. Agent identities are versioned: you can rotate cryptographic keys while the DID that downstream systems and policies rely on remains unchanged.

Identity extraction types

The Identity element’s Identity Extraction Type selector determines how the gateway resolves a DID for a request. Two of the five extraction types are not currently selectable, and a further restriction applies when the element is placed on a Transit Point rather than an Access Point or target leg.

Agent identity using payload extraction

This corresponds to the From Payload (identity metadata) extraction type in the Identity element configuration.

Every agent that talks through Agent Gateway can be given a verifiable cryptographic identity without a registration round-trip. With this extraction type, the gateway reads the identity descriptor already present in protocol metadata, derives a stable fingerprint from configured fields, and issues or reuses the corresponding DID for that exact agent configuration.

How the descriptor is carried depends on protocol:

• A2A: identity is provided as a protocol extension. The agent declares https://fabric.affinidi.io/extensions/agent-identity/v1 in the extensions array and includes the matching descriptor under the same key in metadata.
• MCP: identity is carried in JSON-RPC metadata under _meta.agentIdentity, keeping identity context separate from tool parameters across HTTP, SSE, and stdio transports.

From there, the gateway extracts values from configured identity fields, canonicalises and hashes them, and looks up an existing identity mapping. If found, it reuses the same DID. If not, it mints a new identity and issues one for that descriptor. The gateway then replaces the raw identity descriptor in the forwarded request with a signed Verifiable Presentation, so the downstream target receives verifiable identity rather than raw descriptor fields.

Other identity binding options are available for transport and caller-credential based flows, including mTLS, API key, and JWT/OIDC bearer token strategies. These options do not require payload identity descriptors and are configured through source authentication modes.

For payload extraction examples, see Secure a surface and A2A surface starter.

How payload extraction derives identity

This section applies to the From Payload (identity metadata) extraction type. Other extraction types derive the DID from stored credentials, JWT claims, or a static value. No payload parsing is involved.

For this extraction type, derivation happens at request time using protocol metadata and payload fields already present in the request. No separate registration step is required.

Identity schema

Identity derivation relies on a JSON schema that describes the structure of the agent’s request payload. Fields that should contribute to the DID are marked with "x-identity": true. Only those fields are included in the hash computation. All other fields in the payload are available for policy evaluation and payload capture but do not affect the DID.

The example below shows a schema where the agent’s LLM provider, model, cloud provider, region, and environment are all marked as identity fields:

{
  "type": "object",
  "properties": {
    "agentIdentity": {
      "type": "object",
      "properties": {
        "llmInfo": {
          "type": "object",
          "properties": {
            "provider": { "type": "string", "x-identity": true },
            "model":    { "type": "string", "x-identity": true }
          }
        },
        "provisioningInfo": {
          "type": "object",
          "properties": {
            "cloudProvider": { "type": "string", "x-identity": true },
            "region":        { "type": "string", "x-identity": true },
            "environment":   { "type": "string", "x-identity": true }
          }
        }
      }
    }
  }
}

Extraction, hashing, and DID assignment

agentIdentity.llmInfo.model=gpt-4|agentIdentity.llmInfo.provider=openai|agentIdentity.provisioningInfo.cloudProvider=aws|agentIdentity.provisioningInfo.environment=production|agentIdentity.provisioningInfo.region=us-east-1

Enabling agent identity

An Identity element placed on a canvas edge captures identity evidence at that point:

Each Identity element is configured independently with an extraction type. No prior registration or credential exchange is required. See Identity element reference for how to add and configure one.

Verifiable Credentials

When identity is enabled, the gateway issues a W3C Verifiable Credential for each agent. The credential’s issuer is the gateway’s own DID, and the subject is the agent’s assigned DID. Claims contain the agent’s extracted identity attributes. The credential is signed with EdDSA (Ed25519).

In a multi-gateway scenario, the issuing gateway wraps the VC in a Verifiable Presentation signed with the agent’s Ed25519 key before forwarding:

The receiving gateway verifies both signatures to determine the identity’s trust level:

Cross-gateway trust

In a multi-gateway architecture, an identity that passes all checks at the receiving gateway is stored as verified. It appears on the Identities tab with a REMOTE badge alongside a VERIFIED badge.

Where identity fits in the gateway

Identity resolution runs inline with every request, within the same pipeline as policy evaluation and trust-registry checks.

Supported DID methods

Gateway DID document

The gateway serves two documents for its own identity:

• /.well-known/did.jsonl: the verifiable did:webvh log. This append-only file records every key rotation event, allowing resolvers to verify the full key history anchored to the gateway’s domain.
• /.well-known/did.json: a parallel did:web document for resolvers that use standard did:web resolution. This document includes an alsoKnownAs field referencing the gateway’s did:webvh DID.

Both endpoints share the same key material and service endpoints. Resolvers that support did:webvh use the log for auditability. Resolvers that only support did:web use the JSON document directly.

Each document includes:

• Ed25519 verification methods for message signing and authentication.
• X25519 key agreement keys for establishing encrypted DIDComm channels.
• A DIDComm service endpoint identifying where DIDComm messages should be delivered.

For the gateway’s DID document to be resolvable by remote parties, the gateway must be accessible at a public HTTPS URL. The gateway’s domain is configured in gateway.json, and the generated DID document points to that domain.

Related

• Surface reference: The AgentSurface is the top-level configuration and runtime entity in the Agent Gateway.
• Surfaces: How the identity extraction type is configured per surface.
• Token exchange and ID-JAG: How an agent’s already-established identity can be exchanged for a token scoped to a different audience, without re-running identity resolution.