Skip to content

Get federation key health

GET
/admin/federation/key-health

Counts the gaps in your instance’s federation encryption setup: approved users with no current key, remote accounts with no known key, peers that never exchanged capabilities, and replaced keys about to expire.

These are counts of stored rows, read one after another. They don’t test that any key works, that a peer is reachable or that anything will be encrypted. Missing user keys are created when the server starts, so users who registered or were approved since then can show up here.

users_missing_keypair_sample lists up to 100 of those users, newest account first, and recent_rotations up to 50 key rows most recently stamped by a rotation, which isn’t the same as the last 50 rotations (see the field below).

To give one user a key now, rotate theirs with POST /admin/federation/users/{ref}/rotate-keys. Needs the federation.read or system.admin capability.

The counts and both lists.

Counts of stored rows and two short lists of examples. Nothing in it is a live check.

object
users_total
required

Total approved users on this instance.

integer format: int64
users_missing_keypair
required

Approved users with no current encryption key. Missing keys are created when the server starts, so this mostly counts users who registered or were approved since then.

integer format: int64
remote_actors_missing_enc_key
required

Accounts on other instances that your instance has cached but has no encryption key for. It records a key only from a like or comment that account sends, when the delivery carries one.

integer format: int64
peers_missing_capabilities
required

Peers that never exchanged capabilities, whatever their status or enabled setting. That includes every peer added with POST /admin/federation/peers. A peer that exchanged them but has no encryption support isn’t counted.

integer format: int64
retained_keys_near_expiry
required

Replaced keys whose grace period ends within the next 7 days. After that, Artist Alley stops using them to decrypt, and a cleanup that runs every hour deletes them later.

integer format: int64
recent_rotations

Up to 50 key rows, newest rotation first. A rotation stamps both the new key and the one it replaced, and a key’s stamp moves to the rotation that later replaces it, so this isn’t a full history. Keys drop out once they’re deleted after their grace period.

Array<object>

One key row and the rotation that last created or replaced it, read from the key table rather than the audit log.

object
user_ref
required
integer format: int64
version
required
integer format: int32
rotated_at
required

When that rotation ran.

string format: date-time
rotated_by_user_ref

Who ran that rotation: the user themselves or an admin. Left out if that account has since been deleted.

integer format: int64
nullable
users_missing_keypair_sample

Up to 100 of the users counted in users_missing_keypair, newest account first.

Array<object>

An approved user with no current federation encryption key.

object
ref
required
integer format: int64
username
required
string
nullable
created

When the account was created. Left out if it has no creation date.

string format: date-time
nullable

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