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.
Authorizations
Section titled “Authorizations ”Responses
Section titled “ Responses ”The counts and both lists.
Counts of stored rows and two short lists of examples. Nothing in it is a live check.
object
Total approved users on this instance.
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.
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.
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.
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.
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.
One key row and the rotation that last created or replaced it, read from the key table rather than the audit log.
object
When that rotation ran.
Who ran that rotation: the user themselves or an admin. Left out if that account has since been deleted.
Up to 100 of the users counted in users_missing_keypair, newest
account first.
An approved user with no current federation encryption key.
object
When the account was created. Left out if it has no creation date.
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 completed