Admin-initiated rotation on behalf of a user

POST

/admin/federation/users/{ref}/rotate-keys

• Local development behind nginx (port 8088 by default)

Compromised-key recovery path. Forces rotation for the named user; the new federation_user_keys row + the demoted previous row both record rotated_by_user_ref = the admin’s ref. Distinct from self-rotation (subject == rotated_by) at the audit row level so operator-initiated recoveries are greppable.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

ref

required

integer format: int64

Subject user.ref whose federation keypair the admin is rotating.

Responses

200

Rotation complete.

Response from the rotation endpoints (/account/security/rotate-federation-keys and /admin/federation/users/{ref}/rotate-keys). The new public key is base64-encoded for transport; clients render it as a verification fingerprint or pass it along to the federation actor profile.

object

user_ref

required

Subject user whose key was rotated.

integer format: int64

new_version

required

Version of the freshly-minted current key. Equals previous_version + 1, or 1 if no prior key existed.

integer format: int32

previous_version

Version of the key just demoted to retained state. 0 when no prior current key existed (defensive — shouldn’t happen post-I-b but documented for completeness).

integer format: int32

new_public_key_b64

required

Base64-encoded 32-byte X25519 public key for the new version.

string

algorithm

required

Always naclbox-x25519-v1 today; recorded for forward-compat.

string

retained_until_days

Grace window applied to the demoted previous key. Read from sysconfig at rotation time; pass-through so the UI can render “your previous key is reapable on YYYY-MM-DD.”

integer format: int32

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed