Rotate Own Key

No API key: the agent calls this itself
As Add Own Key, but only the predecessor may sign the pop, which binds predecessorId. The predecessor is labelled rotated and its revocation booked at the window end (v0.3 §7)
Revocation itself is never self-service: a stolen key must not revoke its siblings

POST /agents/self/keys/rotate/{did}

Rotate Own Key

cURL

curl --request POST \
  --url https://api.humanos.tech/agents/self/keys/rotate/{did} \
  --header 'Content-Type: application/json' \
  --data '
{
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "…",
      "y": "…"
    }
  },
  "evidence": {
    "type": "device-self",
    "proof": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZpYS1yZWcrand0In0.…"
  },
  "regNonce": "k3Jd0Q7bXm2sVQ8hZ1pYt4Rc",
  "pop": "<string>",
  "predecessorId": "did:web:humanos.tech:agent:3f2a9c1e-7b4d-4e8a-9f60-2d1c5b7a8e90#key-1"
}
'

201

{
  "keyId": "did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-2",
  "granted": {
    "assurance": "hardware",
    "binding": "attested"
  },
  "predecessorId": "did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-1",
  "degradedFrom": "hardware"
}

Headers

API-Version · string

Pin request, response, and webhook shapes to a specific dated API version (YYYY-MM-DD). Omit to use the version pinned to your API key (set when the key is created; new keys default to the latest version). New integrations should target the latest version.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-10-16"

Path Parameters

did · string · required

The agent's DID, URL-encoded.

Example:

"did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35"

Body

application/json

cnf · object · required

The agent's public key, as a P-256 JWK. Carried BESIDE the evidence, never inside it: evidence proves where a key lives and does not transport it — for an attestation the key is derived from the signed document and cross-checked against this one.

Example:

{
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "…",
    "y": "…"
  }
}

evidence · object · required

Confinement evidence (v0.3 §16.5). Every key you hold proves it is held: proof is a via-reg+jwt signed by the key over { cnf: { jkt }, aud, nonce, iat } — aud and nonce from POST /agents/register-challenge. device-self (+ proof) grants pop/self; custody (+ proof) pop/custodial; attestation-eat and webauthn chained to a pinned root grant device or hardware and need no proof. Evidence that cannot be checked degrades — an unanchored quote to pop/self, then with proof. Evidence that is wrong is refused with its code; none is refused.

Example:

{
  "type": "device-self",
  "proof": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZpYS1yZWcrand0In0.…"
}

regNonce · string · required

The single-use nonce from POST /agents/register-challenge.

Example:

"k3Jd0Q7bXm2sVQ8hZ1pYt4Rc"

pop · string · required

A via-pop+jwt signed by an EXISTING usable key of this agent: aud the platform DID, nonce the registration challenge, action_hash = digestSRI(JCS({ mandateId: "self:", action: "key_add", params: { cnf } })) — so the PoP binds THIS new key. A rotation signs action: "key_rotate" and params: { cnf, predecessorId }.

predecessorId · string · required

The key to rotate from, which must sign pop. Bound into the PoP, so a proof for one rotation cannot rotate another key.

Example:

"did:web:humanos.tech:agent:3f2a9c1e-7b4d-4e8a-9f60-2d1c5b7a8e90#key-1"

Response

201

application/json

Returns the successor key, the rung it earned, and the predecessor.

keyId · string · required

The key the change concerns, what a mandate pins (D7).

Example:

"did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-2"

granted · object · required

The rung the evidence earned after verification.

Show child attributes

predecessorId · string · required

The key rotated from, now labelled rotated. It stays usable until its rotation window ends.

Example:

"did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-1"

degradedFrom · enum<string>

Present only when the evidence could not be confirmed and a lower rung was granted: what was claimed.

Available options: device, hardware

Example:

"hardware"