> ## Documentation Index > Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt > Use this file to discover all available pages before exploring further. # 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 ## OpenAPI ````yaml /versions/2026-10-16.yaml post /agents/self/keys/rotate/{did} openapi: 3.1.0 info: title: Humanos API description: Humanos API version: '1.0' contact: {} servers: - url: https://api.humanos.tech security: [] tags: - name: humanosApp description: '' paths: /agents/self/keys/rotate/{did}: post: tags: - Agents summary: Rotate Own Key description: >- 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 operationId: agents_selfRotateKey parameters: - name: did required: true in: path description: The agent's DID, URL-encoded. schema: example: did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35 type: string - $ref: '#/components/parameters/ApiVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SelfServiceRotateKeyBody' responses: '201': description: Returns the successor key, the rung it earned, and the predecessor. content: application/json: schema: $ref: '#/components/schemas/AgentKeyRotationEntity' '400': description: >- The body is malformed, or the evidence was refused, its code first in the message: the nonce is unknown, expired, already spent or another organization's (`attestation_nonce_invalid`), the key is not shown to be held (`pop_invalid`), or the evidence is wrong (`attestation_key_mismatch`, `attestation_chain_invalid`, `custody_reference_invalid`). content: application/json: schema: type: object properties: statusCode: type: number example: 400 message: type: string example: 'pop_invalid: registration evidence refused (v0.3 §16.5)' error: type: string example: Bad Request '403': description: >- The change is refused: the DID is not an agent, the agent or its operator is not active, or the `pop` is not by a usable key of this agent over this challenge. content: application/json: schema: type: object properties: statusCode: type: number example: 403 message: type: string example: 'self-service PoP refused: agent_not_bound' error: type: string example: Forbidden '404': description: No agent has this DID. content: application/json: schema: type: object properties: statusCode: type: number example: 404 message: type: string example: agent not found error: type: string example: Not Found components: parameters: ApiVersion: name: API-Version in: header required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-10-16' description: >- 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. schemas: SelfServiceRotateKeyBody: type: object properties: cnf: type: object description: >- 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: type: object description: >- 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: type: string description: The single-use nonce from POST /agents/register-challenge. example: k3Jd0Q7bXm2sVQ8hZ1pYt4Rc pop: type: string description: >- 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: type: string description: >- 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 required: - cnf - evidence - regNonce - pop - predecessorId AgentKeyRotationEntity: type: object properties: keyId: type: string description: The key the change concerns, what a mandate pins (D7). example: >- did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-2 granted: description: The rung the evidence earned after verification. allOf: - $ref: '#/components/schemas/AgentGrantEntity' degradedFrom: type: string description: >- Present only when the evidence could not be confirmed and a lower rung was granted: what was claimed. enum: - device - hardware example: hardware predecessorId: type: string description: >- 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 required: - keyId - granted - predecessorId AgentGrantEntity: type: object properties: assurance: type: string description: Assurance rung the platform VERIFIED. enum: - pop - device - hardware example: hardware binding: type: string description: How the key is bound. enum: - self - custodial - attested example: attested required: - assurance - binding ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.