Rotate my own X25519 federation keypair
POST /account/security/rotate-federation-keys
User self-rotation. Generates a fresh X25519 keypair, demotes the previous current key to retained state with the configured grace window (federation.user_keys.retained_until_days, default 30d), and returns the new key version + public bytes for the UI to render verification feedback. The previous key remains decrypt-capable until the sweeper reaps it post-grace.
Authorizations
Section titled “Authorizations ”Responses
Section titled “ Responses ”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
Subject user whose key was rotated.
Version of the freshly-minted current key. Equals previous_version + 1, or 1 if no prior key existed.
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).
Base64-encoded 32-byte X25519 public key for the new version.
Always naclbox-x25519-v1 today; recorded for forward-compat.
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.”
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Unexpected server error
object
Human-readable error summary
Example
the request could not be completed