Manually add a federation peer

POST

/admin/federation/peers

• Local development behind nginx (port 8088 by default)

Manual peer entry — the operator pastes the peer’s instance URL + display name + the PEM-encoded Ed25519 instance public key (out-of-band coordination between operators). The automated handshake protocol lands in 1.22.B-b and uses the same row shape.

Authorizations

• cookieAuth
• bearerAuth

Request Body ^required

object

instance_url

required

Must be https://, no trailing slash, no path component.

string

display_name

required

string

>= 1 characters <= 200 characters

instance_public_key

required

PEM-wrapped Ed25519 public key. Validated server-side.

string

trust_tier

string

default: connected

Allowed values: connected directory-listed auto-sync

encryption_policy

string

default: plaintext

Allowed values: plaintext e2e-encrypted

enabled

boolean

default: true

notes

string

Responses

201

Peer created.

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

409

Peer with this instance_url already exists.

object

error

required

Human-readable error summary

string

Example

the request could not be completed