AIDRESS
Get startedConceptsSDKs & toolsAPI referenceReferencellms.txt
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

OrderMethodResult
1Ed25519 signature (RFC 9421), keyid matching agent_idagent_key returned inline, status: "rotated", no claim_link
2No signature, agent registered with contact_infoclaim_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

NameTypeRequiredDescription
agent_idstringYesThe 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

CodeReason
403Signature belongs to a different agent_id than the one being rotated
404agent_id not found
422Malformed or expired signature