Manually add a federation peer
POST /admin/federation/peers
Adds another instance to your peer list with the address and Ed25519
public key you give, and marks it connected straight away. Nothing
is sent to that instance.
This is how two Artist Alley instances pair today: each admin adds
the other here. Copy instance_url and public_key_pem exactly
from the other instance’s GET /federation/instance, and check the
fingerprint with its admin. Incoming requests are matched to your
list by that exact address, and the server checks only that the key
is a valid PEM-encoded Ed25519 key, not whose it is. Until the other
side adds yours, it refuses what you send.
instance_url must be https:// and a host with no path.
Surrounding spaces and trailing slashes are removed and nothing else
is changed, so a difference in letter case makes a different
address. An address already in your list gets 409. The address is
checked for shape only: the server doesn’t contact it or check where
it points.
The peer is enabled unless you send "enabled": false. trust_tier
and encryption_policy default to connected and plaintext; both
are labels that nothing in this release acts on. No capabilities are
exchanged with a peer added this way, so nothing you send it is
encrypted.
Needs the system.admin capability.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The other instance’s address, such as https://peer.example: https:// and a host, with no path. Trailing slashes are removed.
The other instance’s Ed25519 public key, PEM-encoded, as its GET /federation/instance gives it in public_key_pem. The server checks that it parses, not who it belongs to.
Responses
Section titled “ Responses ”Peer created.
An instance in your peer list, and where pairing with it stands. Pairing shares nothing by itself: content reaches a peer only once you share it with that peer.
object
The instance’s address, such as https://peer.example, with no path or trailing slash.
The instance’s Ed25519 public key, PEM-encoded. A row you created by
asking to pair holds the placeholder PENDING-HANDSHAKE-RESPONSE
instead; only a confirm from that instance replaces it with a real
key.
A label you can set. Nothing in this release acts on it.
A label you can set. Nothing in this release acts on it, so it doesn’t decide whether what you send this peer is encrypted.
When off, no new activity is queued for this peer, it isn’t asked for suggestions and it isn’t in your public list, whatever its status.
Where pairing stands on your side: pending_outbound (you asked to
pair), pending_inbound (it asked and waits for your approval) or
connected. It’s your instance’s own record, not a sign that the
other instance is reachable or has connected too. Activity is queued
only for peers that are connected and enabled.
When this row was created. It doesn’t change when the pair connects.
The user who added this peer or asked to pair; 0 when the row came from the other instance’s request.
Not recorded in this release, so it’s left out.
Free text you can edit. Pairing adds a dated line here when sending a request or reply fails.
Whether this peer appears in your public GET /federation/peers/visible list, which anyone can read. Off by
default. It’s listed only while it’s also connected and enabled.
Not filled in by this release: always 0001-01-01T00:00:00Z.
Not filled in by this release: always 0001-01-01T00:00:00Z.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication 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 completedPeer with this instance_url already exists.
object
Human-readable error summary
Example
the request could not be completed