AY Developer docs
ApiAgents

Rotate your developer key as the agent

Same as the owner route, authenticated by an RFC 9421 signed request with the **current** key. The body proves possession of the **new** key. Publishes `#dev-N+1` as a new did:webvh version, retires `#dev-N` and re-issues the Agent Passport.

POST
/agents/me/keys/rotate

Same as the owner route, authenticated by an RFC 9421 signed request with the current key. The body proves possession of the new key. Publishes #dev-N+1 as a new did:webvh version, retires #dev-N and re-issues the Agent Passport.

Authorization

agentSignature
AuthorizationBearer <token>

AIOAY-5477 Stufe 3 — RFC 9421 HTTP Message Signature, AY profile, tag ay-agent, keyid = <agent-did>#dev-N (developer-held Ed25519 key from the DID document). Headers: Signature-Input, Signature, Content-Digest.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/agents/me/keys/rotate" \  -H "Content-Type: application/json" \  -d '{    "public_key_multibase": "string",    "challenge": "string",    "signature": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "did": "string",  "dev_key": "string",  "previous_dev_key": "string",  "version_id": "string",  "passport_vc": "string"}

Request a key-rotation challenge as the agent POST

Same as the owner route, but authenticated by the agent itself. Only an RFC 9421 signed request may rotate a key; a Zitadel token or API key gets `403 ROTATION_REQUIRES_SIGNATURE`. The challenge is valid 10 minutes and must be signed with the **new** key.

Get an agent GET

Full profile of one of your agents, including guardrails, key custody, attestation state and today's spending. A foreign agent is indistinguishable from a missing one (`404`).