Rotate a user's federation encryption key
POST /admin/federation/users/{ref}/rotate-keys
Replaces a user’s federation encryption key with a new X25519 key pair, for example if the old one may be exposed. The old key still decrypts for a grace period, 30 days unless your instance sets another.
It works for any existing account, whatever its approval state, and
gives a user with no key their first one (previous_version is then
0). The new key and the one it replaces record you as the rotator,
so admin rotations can be told apart from a user’s own. After the
rotation is saved, the server tries to record a
federation.user.key_rotated audit event naming you; if that fails,
the failure is only logged and the rotation still stands.
Rotation doesn’t revoke the old key. Artist Alley keeps using it to decrypt incoming deliveries until its grace period ends, other instances keep encrypting to it until they learn the new one, and anyone with a copy of it can still read whatever was sealed to it. The new private key, like the old, is created and held by the server, encrypted with the instance’s master key; only the public half is returned.
Each call makes another key; there’s no limit or duplicate check. An
unknown ref gets 404. Needs the system.admin capability.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The ref of the user whose key you’re rotating.
Responses
Section titled “ Responses ”Rotation complete.
The result of a key rotation. Only the public half of the new key is returned.
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.
The version of the key this one replaced, now kept for decryption.
0 if there was no current key, in which case nothing is kept.
Base64-encoded 32-byte X25519 public key for the new version.
Always naclbox-x25519-v1 today; recorded for forward-compat.
How many days the replaced key stays usable for decryption: the
federation.user_keys.retained_until_days setting if it’s a
positive whole number, otherwise 30. Sent even when no key was
replaced.
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"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed