did:key explained: AI agent identity and its limits
A did:key is a decentralized identifier that is an encoded public key. Anyone can derive the key from the string and check a signature offline, so it gives an AI agent a self-issued identity with no registry. It cannot be rotated or deactivated, and it says nothing about who owns the key, so revocation and ownership have to come from somewhere else.
A did:key is a public key written as an identifier
The did:key specification (version 0.9, read on 12 November 2026) defines the syntax in one sentence: "It consists of the did:key prefix, followed by a Multibase base58-btc or base64-url encoded value". For an Ed25519 key, the encoding is:
| Part | Value | Meaning |
|---|---|---|
| Method prefix | did:key: | Says how to read the rest |
| Multibase prefix | z | The text after it is base58-btc |
| Multicodec | 0xed, as the two bytes ed 01 | ed25519-pub, a varint |
| Key | 32 bytes | The raw Ed25519 public key |
The specification's example is did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK. A short script that base58-decodes everything after did:key:z confirms the layout. The input is that example string:
A = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
s = "6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
n = 0
for c in s:
n = n * 58 + A.index(c)
b = n.to_bytes((n.bit_length() + 7) // 8, "big")
print(len(b), b[:2].hex(), b[2:].hex())
Running it gives 34 bytes, the first two ed01, and a 32-byte key. Every Ed25519 key gets the same two-byte prefix, so every such identifier begins z6Mk; the Mandare test suite asserts this for generated keys.
The identifier is therefore not a name that points to a key. It is the key. Nothing needs to be looked up to learn which key an agent claims to use.
Resolving it needs no network
The DID Core Recommendation (W3C, 19 July 2022) gives the general shape: did = "did:" method-name ":" method-specific-id. It calls a DID method "the mechanism by which a particular type of DID and its associated DID document are created, resolved", and then updated and deactivated.
For did:key, resolving is arithmetic. The specification's Read operation says: "Reading a did:key value is a matter of deterministically expanding the value to a DID Document." Creating one is just as light: generate a key pair and encode the public key.
For a platform engineer, the consequence is simple. A verifier that receives a signed request and a did:key can derive the public key from the identifier and check the signature, with no call out. No outbound call is needed, so the check does not depend on a network or an identity provider being up. RFC 9421 request signatures can then be checked against the derived key.
It cannot be updated, rotated or deactivated
The same property has a price. The specification states it directly:
This DID Method does not support updating the DID Document.
and, for deactivation, "Since did:key values are not stored in any registry, they cannot be updated or deactivated." Its security section says the method "is a purely generative method, which means that updates are not supported", and its privacy section says the method "does not support key rotation because the identifier is derived directly from the public key material".
Three practical effects follow:
- A stolen private key is permanent. The attacker can sign as that identifier for as long as anyone accepts it. The specification says that without deactivation, "security incident response for did:key is limited to out-of-band communication."
- A new key is a new identity. Every allow-list, budget and audit record that names the old identifier has to be moved by hand.
- Long use is discouraged. The specification calls using a did:key "for interactions that last weeks to months" "strongly discouraged", and says "Any long-lived did:key essentially becomes a single point of failure". It points to registry-based methods for persistent or high-value use.
For an AI agent that runs unattended, the fix cannot be in the DID. Revocation has to be a separate record that the verifier checks on its own side, for instance a list of refused identifiers or a credential status list. The kill switch entry covers what that record has to do.
It proves control of a key, not ownership
The specification warns about correlation: a did:key is "both globally unique and globally correlatable". Anyone who sees the same identifier in two places knows it is the same key.
It does not say who holds the key. A did:key signature answers "was this signed by the holder of that private key?". It does not answer "which company runs this agent?" or "is a person accountable for it?". To connect a key to an owner, the verifier needs a credential signed by a party it already trusts. The SD-JWT VC entry shows that layer: a signed statement that names the key in a cnf claim.
Which brings up the alternative. did:web trades the self-contained property for the ability to change:
| did:key | did:web | |
|---|---|---|
| Identifier derived from | The public key | A domain name |
| Resolution | Computed locally | HTTPS fetch of a did.json (the spec appends /.well-known when no path is given) |
| Update | Not supported | "the contents of the DID document could change", same DID |
| Deactivate | Not supported | Remove or withdraw the did.json |
| Extra trust required | None | DNS and the web host; the spec has a DNS security section |
Neither method says who owns the key. The did:web specification itself notes that signed proofs show control of a file, and that "It does not prove that the domain operator has the private keys." Pick did:key for short-lived, offline or closed-system identities where the verifier owns revocation. Pick did:web when you need to rotate and can host a file.
Where Mandare fits
Mandare's Passport uses did:key for the owner and for each agent. The statements below were checked against the public repository at commit 327442e (3 October 2026) and apply to @mandarelabs/cli 0.1.0. The Concepts page says: "All identifiers are did:key: verification is offline, no resolver, no phone-home."
- A narrow profile. did-key.ts accepts Ed25519 only, base58-btc only, multicodec
0xed01. A comment in that file names did:web as a possible future organization profile, out of scope for v1. A test in the passport package feeds in a secp256k1 prefix and expects a refusal. - The key must match the identity. In delegation.ts,
verifyPassportthrows when thecnfkey does not equal the agent's DID ("key-substitution refused"). The owner signs the credential asissand the agent is thesub. - Revocation lives outside the DID. Each credential carries a
revocation_refinto a status list, andmandare kill <agent-did>writes the revocation locally. The CLI reference says the gateway "refuses the subject on its next request". That is how the missing deactivation is handled: by the door's own state, not by the identifier.
The limits sit next to those claims:
- The specification discourages weeks to months. The default passport validity in
mandare passport issueis 90 days, changeable with--valid-days. Short expiry and local revocation limit the exposure. They do not rotate anything, and we make no claim that they remove the concern the specification raises. - The agent's key is written to a file under
~/.mandare/agents(directory mode 0700). It is not in a hardware module. - There is no owner verification. The attestation in the demo below reads
KYC level 1, mock:local: a mock provider behind an interface. Mandare does not verify who an owner is, which is why we say "signed identity" and nothing stronger.
The transcript comes from docs/demos/S4-mandate-demo.txt in the repository, with one key shortened by the demo itself and a cut marked …:
[owner] passport issued for agent did:key:z6MksQajWTbUA82s…
chain: authority → owner (KYC level 1, mock:local) → agent
…
registered agent:did:key:z6MksQajWTbUA82sF1xtwjJ664a92H9MrpTAvBUUGNMsz4mi (index 0, @ 2026-09-27T05:32:04.662Z, entry 6979b9a57adb…)One more limit: Signature-Agent carries the agent's did:key as a bare string, where the Web Bot Auth draft asks for a dictionary of https URIs. No interoperability with Web Bot Auth verifiers is claimed or tested; the Web Bot Auth entry has the details.
Questions
What is a did:key?
A did:key is a decentralized identifier whose method-specific part is a multibase-encoded public key. The DID document is computed from the string itself, so resolving it needs no network and no registry. For Ed25519 the string starts with did:key:z6Mk.
Can a did:key be rotated or revoked?
No. The did:key specification says the method does not support updating or deactivating the DID document, because the identifier is derived from the public key and stored in no registry. A new key is a new identifier. Revocation has to live in a system the verifier already trusts, such as its own state or a credential status list.
What is the difference between did:key and did:web?
A did:key is derived from a public key and resolved by computation. A did:web is derived from a domain name and resolved by fetching a did.json file over HTTPS. A did:web document can change while the identifier stays the same, which allows rotation. It also depends on DNS and on whoever runs the web host.
Does a did:key prove who owns an AI agent?
No. It proves that whoever signs holds the private key behind the identifier. Linking that key to a person or company needs a separate credential, signed by a party the verifier trusts. The identifier alone carries no owner information.
Is did:key suitable for long-running agents?
The specification discourages it for interactions that last weeks to months, and warns that a long-lived did:key becomes a single point of failure. If you use one for an agent anyway, keep the credentials around it short-lived and keep revocation outside the DID.
Sources
- The did:key Method v0.9 · w3c-ccg
- Decentralized Identifiers (DIDs) v1.0 · W3C · 2022-07-19
- did:web Method Specification · w3c-ccg
Run it yourself: 3 commands, no API keys.
github.com/mandarelabs/mandare →