Keys and custody
Which keys appear in an agent's DID document, who holds them, and what each key may be used for.
An agent's DID document lists one or more verification methods. The fragment after # tells you which key you are looking at and who controls it.
Key fragments
| Fragment | Held by | Purpose |
|---|---|---|
#key-1 | AY, in a hardware-backed key store (KMS) | Signs the DID log and, for platform custody, the Agent Card. |
#key-1-jwk | AY | The same key as #key-1 in JWK form, for verifiers that do not support Multikey. |
#dev-1, #dev-2, … | You | Your Ed25519 request-signing key. Present only for level 3 agents. The number increases with every rotation. |
All keys are Ed25519. Multikey values start with z6Mk: the byte prefix 0xed01 followed by the 32 public-key bytes, base58btc encoded.
Verification relationships
A key may appear in several relationships. The relationship decides what a verifier accepts the key for.
| Relationship | Accepts the key for |
|---|---|
authentication | Signing HTTP requests (RFC 9421). A request signature with a key that is not in authentication is rejected. |
assertionMethod | Signing credentials. |
keyAgreement | Agreeing on encryption keys. |
Your #dev-N key is listed under authentication and assertionMethod.
Key custody
key_custody is a property of the agent and is visible in GET /api/v1/agents/me, in the Agent Passport, and in the Agent Card extension.
key_custody | Request key | Authentication method |
|---|---|---|
platform | AY holds the DID key. The agent authenticates with a Zitadel credential instead. | Authorization: Bearer <access token> |
developer | You hold #dev-N. AY never sees the private key. | RFC 9421 signature, tag ay-agent |
Custody is set at registration: pass public_key_multibase to get developer, omit it to get platform. There is no migration between the two. To move an existing agent to developer custody, register a new agent.
Rotation
- Developer key: a rotation is a new version in the DID log.
#dev-2enters the document,#dev-1leaves it. You prove possession of the new key before the platform writes the entry. See Rotate keys and credentials. - Platform key
#key-1: rotated by AY. Verifiers that re-verify the log see the change; nothing changes for you. - Zitadel credential: replaced by
POST /api/v1/agents/{id}/credentials/rotate. Tokens already issued stay valid until they expire.