Rotate my federation encryption key
POST /account/security/rotate-federation-keys
Replaces your federation encryption key with a new X25519 key pair and returns its public half. Your previous key is kept for decryption for a grace period, 30 days unless your instance sets another.
This is the key used to encrypt federated activity sent to and from your account. It isn’t your instance’s Ed25519 signing key, and rotating it doesn’t change how requests are signed. The server creates the new private key and keeps it encrypted with the instance’s master key; it’s never returned. The response gives the new version, the one it replaced and the new public key in base64 (32 bytes, not PEM).
Rotating doesn’t re-encrypt anything already sent or undo anything sent in plaintext. Other instances learn your new public key only when a like or comment from you reaches them; until then they keep encrypting to the old one, which works while it’s retained. Once the grace period ends, Artist Alley stops using the old key to decrypt what arrives, and a cleanup that runs every hour deletes it later.
Each call makes another key; there’s no limit or duplicate check. Any signed-in user can rotate their own key, with no password or other check.
Authorizations
Section titled “Authorizations ”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"}Unexpected server error
object
Human-readable error summary
Example
the request could not be completed