AY Developer docs
ApiAgents

Request a key-rotation challenge as the agent

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.

POST
/agents/me/keys/rotate/challenge

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.

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/agents/me/keys/rotate/challenge"
{  "challenge": "string",  "expires_at": "2019-08-24T14:15:22Z",  "current_dev_key": "string",  "next_dev_key": "string"}

Read your own agent profile GET

The agent authenticates itself. Send exactly one credential per request: | Method | How | Custody | |---|---|---| | Zitadel access token | `Authorization: Bearer <access_token>` (JWT, RS256, `aud` = project `392496763820310530`) | `platform` | | RFC 9421 signature | `Signature-Input`, `Signature`, `Content-Digest`; tag `ay-agent`; `keyid` = `<did>#dev-N` | `developer` | | Legacy API key (deprecated) | `Authorization: Bearer ay_agent_…` | `platform` | `Signature-Input` together with `Authorization` is rejected with `400 ambiguous_auth`. After authentication the agent must be `active` (`401 AGENT_INACTIVE`), not halted (`403 AGENT_HALTED`), under its daily limit (`403 DAILY_LIMIT_EXCEEDED`) and, for business agents, the owner's BusinessVerificationCredential must be valid (`403 OWNER_NOT_VERIFIED`). With the deprecated API key the response carries `Deprecation: @1790380800` (RFC 9745) and `Sunset: Fri, 03 Apr 2027 00:00:00 GMT` (RFC 8594). No route rate limit.

Rotate your developer key as the agent POST

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.