Skip to content

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.

ref
required
integer format: int64

The ref of the user whose key you’re rotating.

Rotation complete.

The result of a key rotation. Only the public half of the new key is returned.

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

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.

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

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.

integer format: int32

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"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed