Send a pairing handshake to this instance
POST /federation/peers/handshake
Receives another instance’s pairing request (an offer) or its
reply accepting one (a confirm). Anyone can call it without
signing in: the envelope is signed with the key it offers, and the
request has no HTTP Signature.
This instance checks that protocol is aa-handshake/v1, from is
an https:// address with no path, timestamp is within five
minutes of its clock, the signature verifies with
from_public_key_pem, and to matches its base URL as it was when
the app started. The signature shows the envelope wasn’t changed
after it was signed. It doesn’t show that the key belongs to the
instance named in from, which is why an admin checks the key
before accepting.
A new offer becomes a request waiting for an admin to accept; a
confirm completes a request this instance sent. The response’s
status says what happened.
As shipped, two Artist Alley instances can’t pair this way. They
send envelopes to /federation/peers/handshake, without the
/api/v1 prefix this endpoint is served under. They also sign a
supported_capabilities field that this endpoint drops before
checking the signature, so the check would fail. Envelopes that hold
only the fields below, sent to this URL, aren’t affected.
Request Body required
Section titled “Request Body required ”object
The signed part of a handshake. Only these fields are read, and the signature is checked over them alone.
object
Always aa-handshake/v1
The sender’s address: https:// and a host, with no path.
The Ed25519 public key the sender offers, PEM-encoded. The signature must verify with it.
The receiver’s base URL as its site setting stood when the app started (letter case aside).
Any non-empty string; senders use 32 random hex characters. It isn’t checked for reuse.
Within five minutes of the receiver’s clock. The safe form is UTC ending in Z, with no trailing zeros after the decimal point: the receiver re-encodes the timestamp before checking the signature, and that can change other spellings.
Standard Base64 Ed25519 signature over envelope in RFC 8785 canonical JSON, made with the key in from_public_key_pem.
Responses
Section titled “ Responses ”The envelope passed every check. status says what this instance did with it.
object
What this instance did with the envelope:
accepted_pending: it saved a new offer as a request for an admin to accept.completed: it marked the pair connected. For a confirm, it also saved the confirm’s key; for an offer from an instance it had asked first, it didn’t save the offered key.ignored_duplicate: it already had a row for the sender and changed nothing. That row may still be pending.
The id of the receiver’s own row for the sender.
The envelope failed one of the checks above, or it’s a confirm from an instance this instance hasn’t asked to pair.
object
Human-readable error summary
Example
the request could not be completedThis instance’s federation key isn’t available (see GET /federation/instance).
object
Human-readable error summary
Example
the request could not be completed