Rotate keys and credentials
Replace a developer key with a new DID log version, or replace a Zitadel credential.
Rotate a developer key
A rotation writes a new version into the agent's DID log: #dev-2 enters the document, #dev-1 leaves it, #key-1 and the services stay. The platform signs the log entry with its update key after you prove possession of the new key.
As the owner
Request a challenge with the owner's OIDC token.
curl -X POST https://api.aytwin.ai/api/v1/agents/$AGENT_ID/keys/rotate/challenge \
-H "Authorization: Bearer $AY_OIDC_TOKEN"{ "challenge": "…", "expires_at": "…", "current_dev_key": "…#dev-1", "next_dev_key": "…#dev-2" }Generate the new key pair and sign the challenge bytes with the new private key.
Submit the new public key, the challenge, and the signature.
curl -X POST https://api.aytwin.ai/api/v1/agents/$AGENT_ID/keys/rotate \
-H "Authorization: Bearer $AY_OIDC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"public_key_multibase": "z6Mk…new", "challenge": "…", "signature": "…"}'{ "dev_key": "…#dev-2", "previous_dev_key": "…#dev-1", "version_id": "2-Qm…", "passport_vc": "eyJ…" }Switch your signer to the new key immediately. The old key is rejected on every route from this moment (401 signature_invalid). The passport is re-issued with the new dev_key.
As the agent itself
The agent can rotate without the owner, using POST /api/v1/agents/me/keys/rotate/challenge and POST /api/v1/agents/me/keys/rotate with the same bodies. Both calls must be signed with the current key (tag ay-agent). A token or an API key is not enough: 403 ROTATION_REQUIRES_SIGNATURE.
Errors
| Status | Code | Meaning |
|---|---|---|
| 409 | ROTATION_NOT_ALLOWED | The agent has no developer key or is not active. |
| 409 | ROTATION_CHALLENGE_MISSING | Request a challenge first. |
| 410 | attestation_expired | The challenge is older than ten minutes. |
| 422 | attestation_invalid | The signature does not verify or the challenge does not match. |
| 422 | INVALID_PUBLIC_KEY | Not an Ed25519 Multikey, or the same key as before. |
Rate limit: ten rotations per ten minutes.
Rotate a Zitadel credential
For platform custody, replace the credential with a new one. AY creates the new key or secret first, then removes the old one at the identity provider.
curl -X POST https://api.aytwin.ai/api/v1/agents/$AGENT_ID/credentials/rotate \
-H "Authorization: Bearer $AY_OIDC_TOKEN"The response contains credentials exactly once, in the same shape as at registration. Tokens that were already issued stay valid until they expire. To cut them off immediately, turn on the kill switch.
| Status | Code | Meaning |
|---|---|---|
| 409 | AGENT_INACTIVE | The agent is deactivated. |
| 409 | AGENT_CREDENTIAL_NOT_ROTATABLE | The agent has no Zitadel credential (developer custody or legacy). |
| 502 | AGENT_CREDENTIAL_FAILED | The identity provider did not accept the change. Nothing was changed. |
Rate limit: five rotations per hour.
Verify requests from twins
What your agent must check before it accepts a signed call from an AY twin, what the signed scope means, and why the sender check is yours to make.
Revoke an agent
Deactivate an agent for good, what happens in the DID log and at the identity provider, and how a business suspension affects agents.