Initiate an outbound handshake

POST

/admin/federation/peers/initiate

• Local development behind nginx (port 8088 by default)

Admin “Pair by URL” entry. Creates a local pending_outbound row + sends a signed offer envelope to the peer. Idempotent on instance_url.

Authorizations

• cookieAuth
• bearerAuth

Request Body ^required

object

instance_url

required

Peer’s instance URL (https, no path, no trailing slash).

string

display_name

Optional; defaults to the URL host. Operator can rename later from the peer detail page.

string

Responses

201

Local pending_outbound row created (offer POST may have failed; check notes).

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