Skip to content

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.

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

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed