Skip to content
Artist Alley

Aggregate federation key + capability health

GET
/admin/federation/key-health

Admin observability surface. One round-trip feeds the /admin/federation/key-health dashboard’s five tiles: users without keypair (I-b backfill gap), remote actors missing encryption keys (I-c cache miss), peers without capabilities (I-d negotiation miss), retained keys near expiry (sweeper preview), and the total approved-user count for denominator context. Drill-down rows for “users missing keypair” + “recent rotations” ride along so the page renders without separate calls.

Authorizations

Section titled “Authorizations ”

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Aggregate health counts + drill-downs.

Aggregate counts feeding the /admin/federation/key-health dashboard. Five counts in one round-trip; drill-down endpoints ( ListUsersMissingKeypair, ListRecentRotations) cover the per-row detail when the operator follows a tile.

object
users_total
required

Total approved users on this instance.

integer format: int64
users_missing_keypair
required

Approved users with no current federation_user_keys row. Healthy steady state = 0; non-zero surfaces the I-b boot backfill gap.

integer format: int64
remote_actors_missing_enc_key
required

Federation_remote_actors rows whose encryption_public_key is NULL. Pre-I-c peers OR a peer who hasn’t yet emitted an inbound activity carrying their key.

integer format: int64
peers_missing_capabilities
required

Federation_peers rows that haven’t completed I-d capability negotiation. Surfaces the “needs re-pair” cohort.

integer format: int64
retained_keys_near_expiry
required

Retained federation_user_keys rows whose retained_until trips in the next 7 days. Preview of what the sweeper will reap soon.

integer format: int64
recent_rotations

Last 50 rotations across all users; ordered newest first. Surfaced inline so the dashboard renders without a separate round-trip.

Array<object>

Audit-style projection of a single rotation. Pulled from federation_user_keys.rotated_at + rotated_by_user_ref so the dashboard renders without joining audit_events.

object
user_ref
required
integer format: int64
version
required
integer format: int32
rotated_at
required
string format: date-time
rotated_by_user_ref

User.ref of whoever triggered the rotation. NULL when the original triggering admin has since been deleted (the FK is ON DELETE SET NULL). Equals user_ref for self-rotation; differs for admin-initiated recovery.

integer format: int64
nullable
users_missing_keypair_sample

Per-user drill-down on the “users missing keypair” tile. Up to 100 rows; oldest-account-first so the operator can prioritise long-standing gaps.

Array<object>

Drill-down row for the “users missing keypair” tile on the admin federation health dashboard.

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

When the user record was created. Old creation date + no keypair = the I-b boot backfill missed them across reboots.

string format: date-time
nullable

401

Section titled “401 ”

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

403

Section titled “403 ”

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed