Edit a federation peer (tier / encryption_policy / enabled / notes / display_name)

PATCH

/admin/federation/peers/{id}

• Local development behind nginx (port 8088 by default)

Cannot change instance_url or instance_public_key — those require defederate + re-pair (the public_key change in particular signals re-handshake).

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body ^required

PATCH shape — every field optional. Omitting a field leaves it unchanged. instance_url and instance_public_key are NOT editable; defederate + re-pair to change them.

object

display_name

string

>= 1 characters <= 200 characters

trust_tier

string

Allowed values: connected directory-listed auto-sync

encryption_policy

string

Allowed values: plaintext e2e-encrypted

enabled

boolean

notes

string

share_in_visible_list

Per-peer opt-in for peer-of-peer discovery (Phase 1.22.B-d). Toggle this to expose the peer in our /federation/peers/visible response so other peers can surface it as a suggestion.

boolean

Responses

200

Updated peer.

One row from the federation_peers registry (Phase 1.22.B-a + ADR 0043 §“Trust model”). Pairing alone shares no content — see federation_shares (1.22.C) for the access-control layer.

object

id

required

string format: uuid

instance_url

required

Https://peer.example (no trailing slash, no path)

string

display_name

required

string

instance_public_key

required

PEM-wrapped Ed25519 public key (RFC 8410). May be the placeholder string PENDING-HANDSHAKE-RESPONSE while status is pending_outbound — the peer’s real key replaces it when the confirm envelope arrives.

string

trust_tier

required

string

Allowed values: connected directory-listed auto-sync

encryption_policy

required

string

Allowed values: plaintext e2e-encrypted

enabled

required

boolean

status

required

Handshake state machine (migration 00052 + v1.md §11). Outbound delivery (1.22.D) gates on connected only.

string

Allowed values: pending_outbound pending_inbound connected

handshake_at

required

string format: date-time

handshake_by_user_ref

required

integer format: int64

last_seen_at

string format: date-time

nullable

notes

required

string

share_in_visible_list

Per-peer opt-in for peer-of-peer discovery (Phase 1.22.B-d). When true, this peer appears in GET /federation/peers/visible — other peers can then surface it as a discovery suggestion. Default false; explicit opt-in.

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

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

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed