Decentralised Identifiers (DIDs) Guide

A decentralised identifier (DID) is a URI that resolves to a document of public keys and service endpoints controlled by whoever holds the matching private keys, so the security of every credential, signature or agent interaction tied to it rests on the DID method and on how the controller keys are protected. DIDs appear in verifiable credentials, digital identity wallets and, increasingly, proposals for AI agent and workload identity. Teams adopting them face choices the specification deliberately leaves open: which method, who runs resolution, how keys rotate and what happens when a key is lost. This guide explains the DID data model, resolution, the main methods and their trade-offs, controller key management, privacy, and when a DID is the right tool compared with X.509 certificates or SPIFFE. It is written for identity architects, wallet and verifier developers and security reviewers. For how DIDs are used inside credentials, see the Verifiable Credentials Guide.

Key takeaways

The standard defines the data model, not the trust. W3C DID v1.0 is a Recommendation (19 July 2022); each DID method is a separate specification that defines how identifiers are created, resolved, updated and deactivated.
Method choice is a security decision. did:key cannot rotate or deactivate; did:web inherits the security of DNS, TLS and your web server; ledger-based methods add their own governance and availability properties.
Resolution is where verifiers get fooled. The DID Resolution specification asks clients to let users choose which resolvers they trust per method and distinguishes verifiable from unverifiable resolution.
Controller keys are privileged non-human credentials. Whoever holds the key in capabilityInvocation or the controller role can rewrite the document, so protect it like a signing CA key.
Registry listing is not endorsement. The W3C DID Extensions note lists methods against formal criteria; it does not review their security.

What a DID is and how the data model works

A DID is a URI with the did: scheme, a method name and a method-specific identifier, for example did:web:example.com. The DID identifies a DID subject, which can be a person, organisation, thing or abstract concept. Resolving the DID returns a DID document; a DID controller is an entity able to change that document, and a DID can have more than one controller.

Property	Purpose	Security note
`id`	The DID itself; required	Verifiers must check the resolved document's id matches the DID requested
`controller`	Who may change the document	A different controller DID means trusting a second key set
`verificationMethod`	Public keys and their types	Algorithm and key type must meet your crypto policy
`authentication`	Keys that prove control in a login or challenge	Separate from keys used to sign credentials
`assertionMethod`	Keys used to sign statements such as credentials	Verifiers should require the issuing key to be listed here, not only present
`keyAgreement`	Keys for establishing encrypted channels	Keep separate from signing keys
`capabilityInvocation` and `capabilityDelegation`	Keys that invoke or delegate capabilities, often including updating the DID document	The most privileged keys in the document
`service`	Endpoints for interaction with the subject	Endpoints are attacker-controlled input if the document is compromised
`alsoKnownAs`	Other identifiers for the same subject	Does not prove the other identifier agrees

A DID URL adds a path, query or fragment to point at a specific resource, such as did:example:123#key-1 for a single key. The next version of the core specification, DID v1.1, was a W3C Candidate Recommendation Snapshot dated 5 March 2026 when checked in October 2026; it may still change before reaching Recommendation.

Resolution and dereferencing

Resolution takes a DID and returns a DID document plus metadata; dereferencing takes a DID URL and returns a resource, using resolution first. The W3C DID Resolution specification was a Candidate Recommendation Draft dated 25 October 2026 when checked, with some features marked at risk.

Function: resolve(did, resolutionOptions) returns didResolutionMetadata, didDocument and didDocumentMetadata. Options include versionId and versionTime for historical versions.
Document metadata: created, updated, versionId and deactivated, which must be true for a deactivated DID. Check it on every verification.
Errors: defined error types include invalid DID, method not supported, not found and internal error. Treat any error as a failed verification, never as a fallback to cached or default keys.
Resolver trust: the specification says clients must let users choose which resolvers they trust for each method, and separates verifiable resolution (with integrity guarantees to the extent the method allows) from unverifiable resolution. It cautions against relying on controller-attested metadata for business logic.
Local versus remote resolvers: a remote "universal" resolver is convenient but becomes a trusted third party that can return any document. For high-value verification, run resolution locally or use a resolver you operate, and cache with short, explicit lifetimes.

Choosing a DID method

Methods differ in where the document lives, who can change it and what history exists. The table covers patterns rather than every registered method.

Method pattern	Where the document comes from	Rotation and deactivation	Main risks	Good fit
did:key	Generated from the public key in the identifier; no registry	Not supported; a new key means a new DID	Key compromise gives the attacker permanent control of that identifier	Ephemeral sessions, peer exchanges, testing
did:web	A `did.json` file served over HTTPS from the domain (for example `/.well-known/did.json`)	Edit or remove the file	DNS spoofing, web server or hosting compromise, no built-in history	Organisations with an established domain, such as credential issuers
Ledger or log anchored methods	A blockchain or verifiable log	Defined by the method, often with history	Method governance, ledger availability, fees, implementation maturity	Cases needing tamper-evident history without a single web host
Peer methods	Exchanged directly between parties	Defined by the method	Limited to the parties involved	Private pairwise relationships

did:key: the specification (v0.9 draft) states that updates are not supported, that there is no way to signal verifiers that a did:key should no longer be trusted, and that using a did:key for interactions lasting weeks to months is strongly discouraged unless there is high confidence in hardware isolation.
did:web: the method specification maps colons to path segments, does not define any authentication for updates, recommends DNSSEC against spoofed records, requires TLS in line with NIST SP 800-52 Rev. 2, and notes that DNS providers and the web server can observe resolutions. Hashlinks may be used to verify integrity. See the DNSSEC Deployment Guide.
Registered methods: the W3C Decentralized Identifier Extensions Group Note lists methods that meet formal submission criteria and says the registries list mechanisms without choosing between them. Assess any method yourself: specification maturity, number of independent implementations, governance, and how it handles key compromise.

Controller key management

The DID is only as trustworthy as the keys that can change its document. Treat these keys as privileged non-human credentials with an owner, custody rules and a recovery plan.

Separate keys by relationship: distinct keys for updating the document, for signing credentials (assertionMethod), for authentication and for key agreement. A leaked authentication key should not let an attacker rewrite the document.
Hardware custody: keep update and assertion keys in an HSM or cloud KMS with non-exportable keys; for did:web, protect the deployment pipeline that publishes did.json as tightly as the key itself.
Planned rotation: add the new key to the document, start signing with it, keep the old key listed for verification for an agreed overlap period, then remove it.
Recovery: decide before you need it how you recover from loss or compromise of the update key: a second controller, a pre-committed recovery key, or a method feature. did:key has no recovery.
Deactivation: know how to deactivate under your method and how verifiers will learn of it.

The danger of a signing key that outlives its intended life is well illustrated by the Microsoft Storm-0558 Key Breach, where a consumer signing key that should have been retired was used to forge tokens accepted by enterprise mail, because issuer and scope checks were missing. DID verifiers face the same class of risk if they accept any key in a document without checking its verification relationship and the document's status. See the Cryptographic Key Management Guide.

Privacy considerations

Correlation: a single long-lived DID used with many verifiers lets them link activity. Use pairwise or per-relationship identifiers for individuals where the method supports it.
Resolution leaks: for did:web, the hosting server and DNS provider see who resolves which DID and when. The method specification suggests DNS over HTTPS or a trusted resolver to reduce tracking.
Public documents: never put personal data in a DID document, especially on ledger-based methods where data cannot be removed.
Service endpoints: endpoints can reveal infrastructure and become targets; publish only what interactions require.

Where DIDs fit: comparison with other identifier systems

Need	DID	X.509 PKI	SPIFFE
Who vouches for the identifier	The controller; trust comes from method, resolver and external trust lists	A certificate authority hierarchy	The trust domain's SPIFFE issuer
Cross-organisation use without a shared CA	Designed for it	Needs cross-certification or public CA	Needs federation between trust domains
Short-lived workload credentials	Possible but not the core design	Common with automation	Core design
Revocation and status	Method deactivation; credential status lists for credentials	CRL and OCSP	Short lifetimes and bundle updates
Ecosystem maturity in enterprise tooling	Growing, varies by method	Mature	Mature in cloud-native platforms

For workloads inside one organisation, SPIFFE or managed workload identities usually remain simpler; see the SPIFFE and SPIRE Guide. DIDs are most useful where parties that do not share a CA or identity provider need to verify keys and statements from each other: credential issuers, wallets, and cross-organisation AI agent interactions. Track agent-related proposals in the Agent Identity Standards Tracker.

Implementing DID verification safely

Allowlist methods: accept only the methods you have assessed; reject others with a method-not-supported result.
Pin resolvers: run or select resolvers per method and record the choice; do not resolve through an arbitrary public endpoint for high-value decisions.
Check the document: id matches, not deactivated, the key used is listed under the right verification relationship, and the algorithm is permitted.
Bind trust separately: decide whether a valid DID is authorised for the purpose through a trust list, registry or governance framework, not from the DID alone.
Pilot in log-only mode: run verification alongside your existing checks and log disagreements before enforcing; keep the existing path available as rollback.
Cache carefully: short time-to-live, invalidated on any verification failure.

Detection and measurement

Issuer side: alert on any change to your DID documents (for did:web, on commits or deploys touching did.json), and compare the published document with the expected version on a schedule.
Verifier side: log resolution errors, deactivated DIDs encountered, key relationship mismatches and resolver latency.
Metrics: share of verifications using pinned resolvers; mean age of active assertion keys; time from key compromise drill start to updated document; unexpected document changes detected (target: zero undetected in drills); percentage of DIDs on assessed methods.

Common failure patterns

did:key for long-lived issuers: an issuer uses did:key and cannot rotate after a key leak.
Trusting any key in the document: a verifier accepts a credential signed with a key listed only for key agreement or authentication.
Unpinned public resolvers: a remote resolver returns a stale or manipulated document and nobody notices.
Unprotected publishing pipeline: anyone with write access to the web host can replace a did:web document.
Confusing valid with trusted: a well-formed DID is treated as an accredited issuer without a trust list check.
Personal data on ledgers: identifiers or service endpoints reveal information that cannot be erased.

Framework mapping

Theme	NIST CSF 2.0	NIST SP 800-53 Rev. 5
Binding identifiers to keys and subjects	PR.AA-02	IA-4 Identifier Management; IA-5
Verifying assertions and credentials	PR.AA-04	IA-8 Identification and Authentication (Non-organizational Users)
Machine and service identifiers	PR.AA-01	IA-3 Device Identification and Authentication; IA-9
Controller key custody and rotation	PR.DS-02	SC-12 Cryptographic Key Establishment and Management; SC-17
did:web name resolution	PR.IR-01	SC-20 Secure Name/Address Resolution Service

Practitioner checklist

Choose DID methods per use case and record why; avoid did:key for anything long-lived.
Separate update, assertion, authentication and key agreement keys.
Hold update and assertion keys in an HSM or KMS; protect the did:web publishing pipeline.
Write and test a rotation, recovery and deactivation procedure.
Allowlist methods and pin resolvers in every verifier.
Check document id, deactivation status and verification relationship on every verification.
Decide authorisation through a trust list or governance framework, not the DID alone.
Enable DNSSEC for domains used with did:web.
Alert on every change to published DID documents.

Decentralised identifiers (DIDs): How they work, method choice and where they fit