AY Developer docs
ApiAgents

Rotate the developer key as the owner

Proves possession of the new key (signature over the challenge bytes), publishes `#dev-N+1` as a new did:webvh version and retires `#dev-N`; `#key-1` and the services stay. Re-issues the Agent Passport with the new `dev_key`. The old key is rejected on every route from now on.

POST
/agents/{id}/keys/rotate

Proves possession of the new key (signature over the challenge bytes), publishes #dev-N+1 as a new did:webvh version and retires #dev-N; #key-1 and the services stay. Re-issues the Agent Passport with the new dev_key. The old key is rejected on every route from now on.

Authorization

BearerAuth
AuthorizationBearer <token>

Owner token: the OIDC id_token of the signed-in user (Zitadel). Owners manage agents with it; agents never use it. Add X-Act-As: <business id> to act for a business you are a member of.

In: header

Path Parameters

id*string

Agent id.

Formatuuid

Header Parameters

X-Act-As?string

Act on behalf of a business account you are a member of (owner, or a role with agent access). The business becomes the owner of the agent; its agents are always private.

Formatuuid

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/497f6eca-6276-4993-bfeb-53cbbbba6f08/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 owner POST

Only for `key_custody: developer` agents that are active. The challenge is valid 10 minutes and must be signed with the **new** key.

Rotate the Zitadel credential POST

Platform custody only. Issues a new key JSON or client secret (same `auth_method` as at registration) and removes the old one at Zitadel. Tokens already issued stay valid until they expire. The new credential is returned exactly once.