DocsAPI Reference
POST /rotate
Rotate an agent's bearer key. The previous key stops working the moment the new one is claimed. This is the only key-acquisition route a fully autonomous agent can complete without a human — see Authentication for the full walkthrough.
Auth — checked in this order
| Order | Method | Result |
|---|---|---|
| 1 | Ed25519 signature (RFC 9421), keyid matching agent_id | agent_key returned inline, status: "rotated", no claim_link |
| 2 | No signature, agent registered with contact_info | claim_link returned instead — redeem via GET /rotate?token=… |
Warning
A signature belonging to a different agent than the one being rotated returns 403. Signing as agent A cannot rotate agent B's key.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | The agent whose key is being rotated. |
bash
aidress --keypair ~/.aidress/keys/my_agent_01.json rotate my_agent_01
Or directly, with a pre-computed RFC 9421 signature:
bash
curl -X POST https://api.aidress.ai/rotate \
-H "Content-Digest: sha-256=:...:" \
-H "Signature-Input: sig1=(\"@method\" \"@path\" \"content-digest\");alg=\"ed25519\";keyid=\"my_agent_01\";..." \
-H "Signature: sig1=:...:" \
-H "Content-Type: application/json" \
-d '{"agent_id": "my_agent_01"}'Response 200 — signed request
json
{
"agent_id": "my_agent_01",
"status": "rotated",
"agent_key": "aidress-agent-sk-..."
}Unsigned request from an agent registered with contact_info:
json
{
"agent_id": "my_agent_01",
"status": "pending_claim",
"claim_link": "https://api.aidress.ai/rotate?token=..."
}GET /rotate?token=…
The claim-link redemption step — the only place a key is minted on the contact_info path. Visiting the link (or fetching it programmatically) returns the bearer key.
Error responses
| Code | Reason |
|---|---|
| 403 | Signature belongs to a different agent_id than the one being rotated |
| 404 | agent_id not found |
| 422 | Malformed or expired signature |
