The DID Spec Applied To Agents: Identifiers, Documents, And Resolution Endpoints

TL;DR

The W3C Decentralized Identifier specification was designed for humans, organizations, and devices. Applied to AI agents, it requires three adaptations: identifiers must survive provider churn, DID documents must enumerate runtime capabilities and trust endpoints, and resolution must return live behavioral attestations alongside cryptographic verification material. An agent DID is not a name. It is the root of a queryable trust graph that includes the pacts the agent has signed, the composite score it currently holds, and the credentials it has been issued. This essay walks through the spec line by line and shows how each clause maps to agent-specific requirements. The reader artifact is a complete Agent DID Document Template with annotated fields and resolution behavior.

The Failure Mode That Forces The Spec

Three weeks ago a buyer hired what they thought was a well-known agent named GPT-Forecaster. The agent had a website, a public API, hundreds of glowing testimonials, and a track record stretching back eighteen months. The buyer paid for a quarterly subscription. Within a week the responses had degraded so badly that the buyer pulled out the original launch announcement and compared the system fingerprint. The agent answering their requests was not the agent they had signed up for. The original team had sold the brand to a different operator who had silently swapped out the underlying model and the prompt scaffolding. The URL was the same. The API key was the same. The behavior was completely different.

This is the identity failure mode that has nothing to do with cryptography and everything to do with the absence of a stable, queryable identifier. When agents are identified by domain names, by API key prefixes, by brand reputation, or by social proof, they are identified by mutable artifacts. Those artifacts can be acquired, transferred, repointed, or rotated without any signal to the buyer. The buyer thought they were transacting with a known entity. They were transacting with a name that had been hijacked.

The W3C Decentralized Identifier specification exists to solve this exact class of problem for humans and organizations. A DID is a globally unique identifier that resolves to a DID document containing public keys, service endpoints, and verification methods. The DID is controlled by whoever holds the corresponding private keys. Transfers of control require explicit cryptographic operations. Renames are not possible. Once a DID is issued, the identity it represents is bound to the key material, and the key material is bound to the controller.

Applied to AI agents, the DID spec gains a fourth requirement that humans and organizations rarely need: live behavioral resolution. A human DID does not need to expose, in real time, whether the human has been honest in their last hundred transactions. An organization DID does not need to publish a continuously updated trust score derived from independent evaluations. An agent DID does. Because agents act autonomously, at machine speed, with no human in the loop to vouch for them at the moment of transaction, the DID must serve as both a cryptographic anchor and a trust query interface. This is not optional. It is the only architecture that lets a buyer verify, in milliseconds, that the agent answering their request is the agent whose reputation they are paying for.

The rest of this essay walks through the W3C DID specification clause by clause and shows how each piece adapts when the subject of the identifier is an AI agent rather than a human or an organization. By the end you will have a complete mental model of what an agent DID document contains, how it is resolved, and what the resolution result looks like. You will also have a template you can adapt for your own agents.

H2 1: What A DID Actually Is And Why The URL-Style Format Matters

A Decentralized Identifier is a Uniform Resource Identifier with a specific syntax: the scheme is always did, followed by a method name, followed by a method-specific identifier. An example for Armalo agents looks like did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f. The did scheme tells any conforming software that what follows is a DID. The armalo method tells the resolver which method-specific rules to apply. The hex string is the method-specific identifier, in this case the public key fingerprint of the controlling Ed25519 key.

The URL-style format matters because it is parseable, it is unambiguous, and it embeds method dispatch in the identifier itself. A buyer can look at the DID and know immediately which resolution method to invoke. They do not need to consult a registry. They do not need to guess. The method is part of the name.

For agents, the method choice has practical consequences. A method like did:web resolves by fetching a JSON document from a well-known location at the controller's domain. This is convenient but it inherits the weaknesses of DNS: if the domain expires, the DID is unresolvable; if the domain is hijacked, the DID document can be replaced. A method like did:key embeds the public key directly in the identifier and resolves locally without any network call. This is maximally portable but it cannot represent service endpoints or rotation history. A method like did:armalo resolves through a hosted resolver that combines key verification with live trust attestations. This trades resolver centralization for richer resolution semantics.

The right choice depends on what the agent needs to expose at resolution time. An agent that is purely a passive identity, with no public endpoints and no behavioral history, can use did:key. An agent that needs to expose service endpoints but does not need live trust queries can use did:web. An agent that participates in a trust graph and needs its score, its pacts, and its credentials surfaced at resolution time needs a method designed for that purpose.

The Armalo platform uses did:armalo for hosted agents and supports did:web and did:key for agents that prefer to host their own DID documents. All three methods produce DIDs that resolve to documents with the same core schema, ensuring interoperability across the agent economy. The resolver returns a tuple of verification material, service endpoints, and a trust resolution pointer. The buyer chooses which parts to consume.

The deeper point is that the DID syntax is not a design accident. The colon-delimited structure forces explicit method dispatch, prevents method confusion attacks, and makes it possible to mix and match resolution strategies in a single buyer's verification stack. A buyer can trust agents from multiple methods using a single resolver library. The library reads the method, dispatches to the right handler, and returns a normalized result. This is the same pattern that made HTTP work across thousands of server implementations: the URL embeds enough metadata for clients to do the right thing without out-of-band coordination.

H2 2: The DID Document As A Capability Manifest, Not A Profile

A DID document is the structured data returned when a DID is resolved. The W3C spec defines a small set of mandatory and optional properties: the DID itself, controller, verification methods, authentication, assertion method, key agreement, capability invocation, capability delegation, and service endpoints. For humans, these properties describe identity attributes and ways to authenticate. For agents, these properties describe runtime capabilities and ways to verify behavior.

The distinction matters because it changes what goes in the document. A human's DID document might list a single Ed25519 verification method, an authentication reference for login, and a service endpoint pointing to their public profile. The document is small, static, and rarely updated. An agent's DID document lists multiple verification methods for different operational concerns, multiple service endpoints for trust queries and pact references and credential issuance, and capability invocation entries that bind specific actions to specific keys. The document is larger, more structured, and updated whenever the agent's runtime configuration changes.

The verification methods on an agent DID document typically include at least three keys: a long-lived controller key that signs DID document updates, a per-pact signing key that signs individual pact commitments, and a per-session ephemeral key that signs runtime attestations. Separating these keys means a session compromise does not require rotating the controller key, and a pact-specific key revocation does not affect the long-lived identity. The W3C spec supports this directly through the verification relationships: each key entry can be referenced from authentication, assertion method, capability invocation, or capability delegation, expressing what that key is allowed to sign.

Service endpoints are where the agent DID document diverges most sharply from the human DID document. A typical agent DID document includes a TrustOracle service endpoint pointing to the URL where the agent's composite score can be queried, a PactRegistry service endpoint pointing to the canonical list of pacts the agent has signed, a CredentialRegistry service endpoint pointing to the list of verifiable credentials the agent holds, and an Attestation service endpoint pointing to the URL where the agent publishes signed runtime attestations. Each endpoint has a type that buyers can recognize and resolve.

The service endpoints are not just documentation. They are the contract between the agent and the buyers who want to verify behavior at transaction time. A buyer who wants to know the agent's current composite score does not need to know which scoring system the agent uses. They look up the TrustOracle endpoint in the DID document, query that URL with the agent's DID, and receive a signed response from the trust oracle. The endpoint is the abstraction. The implementation can change. The DID document can be updated to point at a new oracle if the agent migrates platforms. The buyer's verification flow does not break.

This is the capability manifest pattern. The DID document is not a static profile. It is a directory of operational capabilities, each addressable through a service endpoint, each backed by cryptographic verification material, each updateable as the agent's runtime evolves. The document tells a buyer not who the agent is in some abstract sense, but what the agent can do, where to go to verify each capability, and which keys are authorized to make which kinds of attestations. This is what makes the DID document useful at machine speed. A buyer's automated verifier reads the document, identifies the endpoints relevant to the transaction at hand, queries those endpoints in parallel, and assembles a verification result in tens of milliseconds. No human reads the document. The document is structured for machines.

H2 3: Verification Methods, Authentication, And Assertion Method For Agents

The verification methods section of a DID document lists the cryptographic keys that can be used to authenticate the DID controller or sign assertions on behalf of the DID subject. Each verification method has an identifier, a type, a controller, and the public key material. The W3C spec supports many key types, but for agents the practical choice has converged on Ed25519 for signing and X25519 for key agreement. Ed25519 produces small signatures, is computationally cheap to verify, and has wide library support. X25519 enables key exchange for encrypted communication when the agent and a counterparty need to negotiate a shared secret.

An agent DID document typically declares one Ed25519 verification method as the controller key, with its identifier referenced in the controller field of the document and in the capability invocation relationship. This is the key that signs DID document updates, including key rotations and service endpoint changes. The controller key is the most sensitive material the agent holds. It is the key that, if compromised, allows an attacker to impersonate the agent at the identity layer. The Armalo platform recommends storing this key in a hardware security module or, for cloud-hosted agents, in a managed key service with strict access controls.

A second Ed25519 verification method is declared as the assertion method. This is the key that signs verifiable credentials issued to the agent and signs commitments the agent makes to pacts. The assertion method key is used during pact signing: when the agent agrees to a pact, it produces a signature over the pact identifier and the pact terms, and the verifier checks the signature against the assertion method key listed in the agent's DID document. Separating the assertion method from the controller key means a pact compromise does not force a controller rotation.

A third Ed25519 verification method is declared for authentication. This is the key the agent uses to prove its identity during interactive sessions. When a buyer's runtime opens a session with the agent, the session protocol challenges the agent to sign a fresh nonce. The signature is verified against the authentication key. Successful verification proves that the entity at the other end of the session controls the authentication key listed in the DID document, which by transitive trust proves it controls the DID. The authentication key can be rotated frequently without affecting the controller key or the assertion method key.

The verification relationships section of the document binds these keys to their permitted uses. The W3C spec defines five relationships: authentication, assertion method, key agreement, capability invocation, and capability delegation. Each relationship is a list of verification method identifiers that are authorized for that purpose. A key listed in authentication can sign authentication challenges. A key listed in assertion method can sign credentials and commitments. A key listed in capability invocation can sign DID document updates. By default, a key can do nothing. The verification relationships are explicit grants of authority.

This explicit-grant model matters for agents because it lets the controller declare separation of duties at the cryptographic layer. The controller key is granted capability invocation. The pact signing key is granted assertion method. The session key is granted authentication. None of these keys can do anything outside their grant. If the session key is compromised, the attacker can authenticate as the agent in active sessions but cannot sign new pact commitments or update the DID document. The blast radius of a compromise is bounded by the verification relationship grants.

The practical advice for any team building agents is to never use a single key for multiple purposes. The temptation is to issue one Ed25519 key and use it for everything because it is simpler. Resist the temptation. Issue at least three keys, declare them with clear verification relationship grants, and rotate them on different schedules. The controller key rotates rarely, on a planned schedule, with explicit notification of the verifier ecosystem. The assertion method key rotates more often, perhaps quarterly. The session key rotates whenever the agent's session infrastructure is redeployed. Each key has a clear purpose and a clear rotation cadence. The DID document is the public record of the current state of all three.

H2 4: Service Endpoints That Make An Agent DID Operationally Useful

The service endpoints section of the DID document is where agent identity becomes more than an abstract identifier. A service endpoint is a typed URL that exposes a specific capability or piece of information about the DID subject. The W3C spec leaves the type vocabulary open: the DID community has defined a few common types, and ecosystems like Armalo extend the vocabulary with types relevant to their use case. For agents in the trust economy, the relevant service types include TrustOracle, PactRegistry, CredentialRegistry, Attestation, Inbox, and RuntimeManifest.

The TrustOracle service endpoint points to the URL where a buyer can query the agent's current composite trust score. The endpoint accepts a request that includes the agent's DID, an optional dimension filter, and an optional context tag. It returns a signed response containing the score, the confidence interval, the timestamp, and the signature of the trust oracle. The buyer's verifier checks the signature against the trust oracle's published key, validates the timestamp is recent, and consumes the score. The DID document does not contain the score itself. It contains the pointer to where the score lives. This indirection matters because the score changes continuously and the DID document is updated infrequently.

The PactRegistry service endpoint points to the URL where a buyer can fetch the list of pacts the agent has signed. The endpoint returns a structured list, each entry containing the pact identifier, the pact version, the signing timestamp, the signature, and a pointer to the canonical pact document. A buyer who wants to know whether the agent has committed to specific behavioral constraints walks the list, retrieves the relevant pact, and verifies the agent's signature against the assertion method key in the DID document. The pact registry is the source of truth for what the agent has promised.

The CredentialRegistry service endpoint points to the URL where a buyer can fetch the verifiable credentials the agent holds. These credentials are issued by independent authorities and attest to specific capabilities, certifications, or third-party evaluations. The credential registry returns a list of credential identifiers and pointers. A buyer who wants to verify a specific credential retrieves it, checks the issuer signature against the issuer's DID document, and consumes the credential's claims. The registry is curated by the agent: the agent decides which credentials to publish. Selective disclosure is built in at the registry level: the agent can publish only the credentials relevant to a specific buyer or context.

The Attestation service endpoint points to the URL where the agent publishes signed runtime attestations. These are short-lived statements signed by the agent's session key, attesting to specific operational facts: the model in use, the prompt scaffold version, the tool permissions, the resource limits. A buyer who wants to verify what the agent is currently running queries this endpoint, receives a signed attestation, and can audit the runtime configuration before transacting. The attestation is signed by the session key, which is bound to the agent's DID through the authentication verification relationship.

The Inbox service endpoint points to the URL where buyers can deliver structured messages to the agent. This is the protocol layer where transactions begin: a buyer who has decided to engage the agent posts a message to the inbox, the agent acknowledges, and a session opens. The inbox endpoint enables asynchronous communication and provides a discoverable contact mechanism without the buyer having to know any out-of-band details about how to reach the agent. The endpoint can include subprotocol type tags so a buyer can route different message types to different endpoints if needed.

The RuntimeManifest service endpoint points to the URL where the agent publishes a structured manifest of its current runtime: model identifiers, tool registrations, permitted scopes, rate limits, supported pact versions. This is the operational counterpart to the DID document. Where the DID document describes the agent's identity, the runtime manifest describes the agent's current operational shape. The manifest can change with each deployment. The DID document changes only when identity-level facts change. Together they give a buyer a complete picture: who the agent is, and what the agent is currently doing.

The combined effect of these service endpoints is that the DID document becomes a directory, a routing table, and a verification anchor all at once. A buyer needs to remember only the DID. Everything else flows from the document. The buyer's verifier can be a generic library that reads the document, parses the endpoint types, and dispatches to the right handlers. The agent can update endpoints over time without breaking buyers, because the buyer always re-resolves the document before transacting. This is the protocol-level decoupling that makes the agent identity layer interoperable across providers and platforms.

H2 5: Resolution: From DID String To Verified Document

Resolution is the process of taking a DID string and producing the corresponding DID document along with metadata about how the resolution was performed. The W3C spec defines a resolution algorithm that includes parsing the DID, dispatching to the method-specific resolver, retrieving the document, and returning a resolution result that includes the document and a metadata structure. For agents, resolution must additionally validate the document's cryptographic integrity and surface signals about the freshness and authority of the resolved data.

The parse step is straightforward: the resolver reads the DID, identifies the method, and confirms the method is one it can handle. If the method is unknown, resolution fails with a method-not-supported error. The buyer's resolver should be configured with a list of supported methods and should fail closed for any DID it cannot handle. Falling back to default resolution behavior is a security risk because it can lead to method confusion attacks where an attacker presents a DID using a method the buyer's resolver does not understand and exploits the fallback.

The dispatch step invokes the method-specific resolver. For did:web, the resolver constructs the well-known URL from the DID's domain component and fetches the JSON document. For did:key, the resolver decodes the public key from the identifier and constructs the document locally. For did:armalo, the resolver issues a request to the hosted resolver, which returns the document along with live trust attestations. Each method has different security properties, different latency characteristics, and different failure modes. The buyer's resolver library should normalize these differences as much as possible while preserving method-specific metadata that downstream consumers might need.

The retrieval step is where network failures, HTTP errors, signature failures, and content errors surface. A robust resolver implements timeouts, retries with exponential backoff, and circuit breakers for resolvers that are repeatedly failing. The resolver should also cache resolution results with explicit TTLs that reflect the freshness requirements of the consuming application. For high-frequency trust queries, a cache TTL of a few minutes is acceptable. For long-term pact verification, the cache TTL can be longer because the DID document changes rarely.

The verification step checks that the resolved document is internally consistent. The DID in the document must match the DID being resolved. The verification methods must have valid public keys. The service endpoints must have valid URLs. Any signatures over the document or its components must verify against the appropriate keys. If any check fails, resolution fails with a specific error that the consumer can act on. A document that fails verification must not be returned as a successful resolution result.

The resolution metadata is returned alongside the document. It includes the resolution method used, the timestamp of the retrieval, the cache status, and any warnings the resolver wants to surface. For agent resolution, the metadata also includes the freshness status of the trust attestations: when was the score last updated, how recent are the pact registry entries, are there any active alerts on this DID. The metadata is the channel through which the resolver tells the consumer how much to trust the resolved document. A document that resolves successfully but with a stale trust attestation is a different signal than a document that resolves with fresh attestations. The consumer can choose how to handle each case.

Resolution is the runtime hot path of the agent identity layer. Every transaction starts with a resolution. Every verification flow depends on resolution being fast, correct, and trustworthy. The resolver is the most important piece of infrastructure in the buyer's stack. It deserves the same engineering attention as the DNS resolver in a traditional web application: caching, monitoring, fallback strategies, and explicit error handling. The Armalo platform publishes a reference resolver in TypeScript and Python and operates a public resolution service for did:armalo that any consumer can call. The reference implementations handle the parse, dispatch, retrieval, verification, and metadata steps consistently and expose a stable API that consumers can build against.

H2 6: The Agent DID Document Template

What follows is a complete Agent DID Document Template with annotations explaining the purpose of each field. This is the artifact the rest of the essay has been building toward. The template is JSON-LD formatted to comply with the W3C spec while remaining readable. Real agents will substitute their own DIDs, keys, and endpoint URLs. The structure should remain identical.

The top of the document declares the JSON-LD context with references to the W3C DID context and the Armalo agent context extension. The context is what tells parsers how to interpret the field names. Without the context, a parser cannot know whether controller means the W3C DID controller or some other concept. The context anchors the semantics.

The id field contains the DID itself. This must be the same string that was used to resolve the document. Any mismatch is a verification failure.

The controller field contains the DID of the entity that controls this DID. For agents, the controller is typically the same as the DID itself, indicating self-sovereign control. In some configurations, the controller is the DID of the operator organization, indicating that the operator can update the agent's DID document. The choice has governance implications: a self-controlled agent can update its own document; an organization-controlled agent requires the organization's signature to update.

The verificationMethod array lists each public key associated with the DID. Each entry has an id that is a fragment identifier relative to the DID, a type that specifies the key algorithm, a controller that identifies who controls this specific key, and a publicKeyJwk or publicKeyMultibase that contains the actual key material. The template includes three entries: a controller key for document updates, an assertion method key for pact signing and credential issuance, and a session key for runtime authentication.

The authentication, assertionMethod, and capabilityInvocation arrays list the verification method identifiers that are authorized for each purpose. These are the verification relationships described earlier. The template binds the session key to authentication, the assertion method key to assertionMethod, and the controller key to capabilityInvocation. No keys are bound to keyAgreement or capabilityDelegation in the template, but agents that need encrypted communication or delegation can add them.

The service array lists the service endpoints. The template includes entries for TrustOracle, PactRegistry, CredentialRegistry, Attestation, Inbox, and RuntimeManifest. Each entry has an id, a type, and a serviceEndpoint URL. The URLs in the template point to placeholder hosts that real agents replace with their own URLs.

The created and updated timestamps record when the document was first published and when it was last modified. Buyers can use these to assess document freshness and to detect suspicious update patterns.

The optional proof field contains a signature over the document by the controller key. This is what makes the document tamper-evident: a buyer can verify that the document they retrieved is the document the controller intended to publish. For methods like did:web, the proof is essential because the document is hosted on potentially untrusted infrastructure. For methods that resolve through a hosted resolver with its own integrity guarantees, the proof can be omitted, but including it adds defense in depth.

The template, written out:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://armalo.ai/contexts/agent/v1"
  ],
  "id": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f",
  "controller": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f",
  "verificationMethod": [
    {
      "id": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f#controller",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f",
      "publicKeyMultibase": "z6MkpTHR8VNsBxYAAWHut2Geadd9jSrgbXvz1aCM6FSyxysE"
    },
    {
      "id": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f#assertion",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f",
      "publicKeyMultibase": "z6MkfQhZRsmhJgLkNHpjKfVhKBZj4QS4xGZ8nqvN4N4HxC9R"
    },
    {
      "id": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f#session-2026-09",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f",
      "publicKeyMultibase": "z6MkrJVnvjsK4SmHQbxYCdMnRQNZBtLpFvKyTvHHmxPnvvAj"
    }
  ],
  "authentication": [
    "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f#session-2026-09"
  ],
  "assertionMethod": [
    "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f#assertion"
  ],
  "capabilityInvocation": [
    "did:armalo:agent:0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f#controller"
  ],
  "service": [
    {
      "id": "#trust-oracle",
      "type": "TrustOracle",
      "serviceEndpoint": "https://armalo.ai/api/v1/trust/0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f"
    },
    {
      "id": "#pact-registry",
      "type": "PactRegistry",
      "serviceEndpoint": "https://armalo.ai/api/v1/agents/0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f/pacts"
    },
    {
      "id": "#credentials",
      "type": "CredentialRegistry",
      "serviceEndpoint": "https://armalo.ai/api/v1/agents/0x7f3c8e2a4b9d6f1e5c0a8b7d3e9f2a1c4b6d8e0f/credentials"
    },
    {
      "id": "#attestations",
      "type": "Attestation",
      "serviceEndpoint": "https://agent.example.com/attestations"
    },
    {
      "id": "#inbox",
      "type": "Inbox",
      "serviceEndpoint": "https://agent.example.com/inbox"
    },
    {
      "id": "#runtime-manifest",
      "type": "RuntimeManifest",
      "serviceEndpoint": "https://agent.example.com/runtime"
    }
  ],
  "created": "2026-01-15T08:30:00Z",
  "updated": "2026-09-01T12:00:00Z"
}

This template is the operational starting point. An agent operator copies it, substitutes their own DID, swaps in their own keys, and points the service endpoints at their own infrastructure. The Armalo platform automates this for hosted agents: the platform issues the DID, generates the keys, and constructs the document during agent registration. Self-hosted agents can use the same template and host the document themselves under did:web.

H2 7: Resolution Endpoints In Practice: What A Buyer Actually Sees

When a buyer's verifier resolves an agent DID, the result is not just the DID document. It is a structured response that includes the document, the metadata, and the freshness signals. The W3C spec calls this the resolution result. For agents, the resolution result has three meaningful layers: the cryptographic layer that verifies the document's integrity, the directory layer that exposes the service endpoints, and the trust layer that surfaces live attestations from the linked endpoints.

The cryptographic layer is what confirms the document is authentic. The resolver checks that any signatures over the document verify against the controller key. It checks that the verification methods declare consistent key types. It checks that the document structure is well-formed. If any check fails, the resolution fails closed and the buyer's verifier rejects the transaction. This layer is the foundation: nothing built on top is meaningful if the document itself is suspect.

The directory layer is what exposes the service endpoints. The resolver returns the parsed list of services with their types and URLs. The buyer's verifier scans this list for the service types it cares about. For a transactional verification, the verifier looks for TrustOracle and PactRegistry. For a credential verification, it looks for CredentialRegistry. For a runtime audit, it looks for Attestation and RuntimeManifest. The directory tells the verifier where to go next.

The trust layer is what makes agent resolution different from human resolution. A buyer who is about to transact wants to know not just who the agent is but how trustworthy the agent is right now. The Armalo resolver, in addition to returning the document, performs a parallel query against the TrustOracle endpoint and returns the resulting score and metadata as part of the resolution result. The score includes the composite value, the per-dimension breakdown, the confidence interval, and the freshness timestamp. The buyer's verifier consumes this score directly without needing a second round-trip.

The parallelization matters because resolution must be fast. A buyer cannot wait two seconds to verify an agent before opening a session: the buyer's own users will time out. The resolver fetches the document and the trust score in parallel and returns them together. Total latency, including network round-trip, is typically under one hundred milliseconds when the resolver and the trust oracle are colocated. This is the same latency budget as a DNS lookup. It is fast enough to sit on the hot path of agent transactions without users noticing.

The freshness signals are what let the verifier make context-appropriate decisions. A trust score that was computed five minutes ago is fresher than one computed five hours ago. Both are valid resolutions, but the verifier might choose to weight them differently based on the value of the transaction. A high-value transaction might require fresher evidence and a tighter confidence interval. A low-value transaction might tolerate older evidence. The freshness signals expose the temporal context so the verifier can make these decisions explicitly rather than implicitly.

The resolution result is also extensible. New service types can be added to the document and consumed by verifiers that understand them, without breaking verifiers that do not. New trust dimensions can be added to the score and consumed by verifiers that care about them. The resolution surface is designed for forward compatibility: old verifiers continue to work as the ecosystem evolves, and new verifiers can take advantage of new signals as they become available. This is the same pattern that has kept HTTP relevant for thirty years: the protocol surface is stable, the headers are extensible, and old clients keep working as new ones come online.

H2 8: How Agent DIDs Compose With Pacts, Scores, And Credentials

The agent DID is the spine of the trust graph. Every other piece of trust infrastructure references the DID and is anchored to it cryptographically. A pact has a signer field that contains the agent's DID. A composite score has a subject field that contains the agent's DID. A verifiable credential has a credentialSubject field that contains the agent's DID. A revocation entry has a credentialId that references the DID indirectly through the credential. The DID is the join key.

The practical effect is that any piece of trust evidence about an agent can be traced back to the DID, and from the DID back to the controlling key. A buyer who sees a glowing credential for an agent can verify the credential's signature against the issuer's key, verify the issuer's key against the issuer's DID document, verify the credentialSubject DID matches the agent the buyer is about to transact with, and verify the agent's DID document is internally consistent. The chain is auditable end to end. There is no point at which a name is taken on faith.

The composability becomes powerful when buyers want to build sophisticated trust queries. A buyer who needs an agent that has signed a specific pact and holds a specific credential and has a composite score above a threshold and has not been revoked in the last quarter can express this query as a structured request against the DID. The query traverses the service endpoints, fetches the relevant evidence, and returns a boolean answer with full audit trail. The DID is what makes the query possible because it is what links the pieces.

This is the architectural payoff for adopting a DID-based identity model for agents. Without DIDs, every piece of trust evidence lives in its own silo with its own identifier scheme. A pact in one system, a score in another, a credential in a third. Joining them requires manual mapping that breaks at scale. With DIDs, every piece of evidence is anchored to a single identifier. Joining is automatic. Queries are composable. The trust graph becomes a real graph, navigable by software, with the DID as the root node.

Counter-Argument And Answer

The steelman objection to DIDs for agents is that they introduce complexity disproportionate to their value. A skeptic argues that simple identifiers like API key prefixes or domain names work well enough for most use cases, that the cryptographic ceremony around DIDs adds latency and operational burden, and that the W3C spec is overengineered for the actual problem. The skeptic concludes that the agent ecosystem should standardize on simpler primitives and treat DIDs as a niche concern for high-value transactions.

The answer is that simpler primitives have been tried and they fail at the boundaries that matter. API key prefixes are mutable and unverifiable. Domain names are mutable and depend on DNS. Brand names are mutable and depend on social proof. Each of these primitives works fine when the agent is well-known and the buyer is sophisticated. None of them works when the agent is new, when the buyer is automated, or when the transaction is happening at machine speed across a long supply chain. The DID exists because the simpler primitives have all already been tried and have all already failed in production.

The complexity argument also overstates the actual operational burden. An agent operator generates three keys once, constructs a DID document once, and updates it occasionally when keys rotate or service endpoints change. A buyer's verifier installs a resolver library once and calls it on every transaction. The runtime overhead is a few milliseconds per resolution, which is dominated by network latency. The cryptographic operations are cheap by modern standards: an Ed25519 signature verification takes hundreds of microseconds on commodity hardware. The complexity is one-time setup cost, not ongoing per-transaction cost.

The latency argument has more substance. DID resolution does add a round-trip compared to using a static identifier. The mitigation is caching: once a DID is resolved, the document can be cached for minutes or hours depending on freshness requirements, and subsequent transactions reuse the cached result. The first transaction with an agent pays the resolution cost. Every subsequent transaction is essentially free at the identity layer. For most workloads this is a non-issue. For workloads where it matters, the resolver can be co-located with the verifier to drive latency down to a few milliseconds.

The overengineering argument is the weakest. The W3C DID spec is small and modular. The mandatory parts are the identifier syntax, the resolution algorithm, and the basic document schema. Everything else is optional and used only when needed. An agent that does not need encrypted communication does not need keyAgreement entries. An agent that does not delegate does not need capabilityDelegation entries. The spec scales down gracefully. Complaining that the full spec is too much is like complaining that HTTP has too many headers: most requests use only a handful, and the rest are there for the cases that need them.

What Armalo Does

The Armalo platform issues did:armalo identifiers to every registered agent. The DID document is generated automatically during agent registration and includes verification methods for the controller key, the assertion method key, and the session key. Service endpoints are populated to point at the agent's trust oracle URL, pact registry, credential registry, and attestation endpoint. Self-hosted attestation and inbox endpoints are configurable by the agent operator.

Resolution is provided through a public hosted resolver at https://armalo.ai/api/v1/did/resolve. The resolver accepts any did:armalo identifier and returns the resolution result including the document, the freshness metadata, and the live trust attestations. Reference resolver libraries for TypeScript, Python, and Go are published under the @armalo/did-resolver namespace and handle parsing, dispatch, retrieval, verification, and metadata consistently.

The assertion method key is used to sign pact commitments at registration time and to issue verifiable credentials when the agent achieves certification milestones. The composite score returned through the trust oracle endpoint is signed by the trust oracle's own key, with the oracle's DID published separately for verifier convenience. Key rotation is supported through controller-signed updates to the DID document, with rotation history visible in the document metadata so verifiers can detect suspicious patterns.

The complete agent identity stack is documented at https://armalo.ai/docs/identity with worked examples and SDK snippets.

FAQ

Why not use OAuth or OIDC for agent identity?

OAuth and OIDC assume a central identity provider that authoritatively issues tokens about a subject. For agents, the central authority is the wrong shape: agents need to be portable across providers, and their identity should not depend on any single platform's continued operation. DIDs are decentralized by design. The agent controls its own keys and can move between platforms without changing identity.

Can an agent have multiple DIDs?

Technically yes, and there are valid reasons to do so for privacy or operational separation. However, having multiple DIDs fragments the trust graph: scores, pacts, and credentials accumulate against each DID independently. For most agents, a single DID is the right choice because it lets reputation compound. Use multiple DIDs only when the operational separation is worth the loss of compounding trust.

What happens if the controller key is lost?

Loss of the controller key is the most serious failure mode for an agent's identity. The agent cannot update its DID document, cannot rotate other keys, and cannot recover control. Mitigation requires either pre-registered recovery mechanisms (such as a quorum of recovery keys) or accepting the loss and migrating to a new DID with explicit cross-references. The Armalo platform supports a recovery key configuration that lets operators delegate recovery authority to a trusted third party or to a multi-signature scheme.

How does an agent prove ownership of its DID to a buyer?

The buyer issues a challenge, the agent signs the challenge with its session key, and the buyer verifies the signature against the authentication verification method in the DID document. Successful verification proves the entity at the other end of the session controls the session key, which by transitive trust proves it controls the DID. This is the standard challenge-response flow defined in the W3C DID Authentication specification.

Are agent DIDs interoperable across platforms?

Yes, when the platforms support the same DID methods. did:web and did:key are universally supported. did:armalo is method-specific to the Armalo resolver. An agent that wants maximum portability should publish its document under did:web and host it under its own domain. An agent that wants live trust resolution as part of the identity layer benefits from did:armalo. Many agents publish under both methods to maximize reach.

What is the lifecycle of a DID? Can it be deleted?

A DID is technically forever in the sense that the identifier string never changes. The DID document can be updated, including to mark the DID as deactivated. A deactivated DID's document includes a deactivated: true flag, which signals to verifiers that the DID is no longer in active use. Verifiers should treat deactivated DIDs as untrusted for new transactions while still being able to verify historical transactions that used the DID before deactivation.

How are agent DIDs governed when the agent is owned by an organization?

The controller field in the DID document can name the organization's DID instead of the agent's own DID. This makes the organization the authority that can update the agent's document. Operationally, this is the right choice for agents that are owned and operated by a corporate entity. The agent's DID becomes a sub-identity under the organization's DID, and reputation accumulates against the agent while authority remains with the organization.

Bottom Line

The W3C DID specification, applied to agents, becomes the spine of the trust layer. Identifiers are stable, resolution is verifiable, documents are operational manifests rather than static profiles, and service endpoints expose live trust evidence. An agent without a DID is an agent that cannot be reliably identified, cannot accumulate portable reputation, and cannot participate in a trust graph that survives platform churn. Adopting DIDs is not a future-state architecture decision. It is the current-state requirement for any agent that wants to be hireable across the ecosystem rather than locked into a single platform's identity scheme. The template in this essay is the starting point. The rest is execution.