Skip to content

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.

object
envelope
required

The signed part of a handshake. Only these fields are read, and the signature is checked over them alone.

object
protocol
required

Always aa-handshake/v1

string
type
required
string
Allowed values: offer confirm
from
required

The sender’s address: https:// and a host, with no path.

string
from_display_name
required
string
from_public_key_pem
required

The Ed25519 public key the sender offers, PEM-encoded. The signature must verify with it.

string
to
required

The receiver’s base URL as its site setting stood when the app started (letter case aside).

string
nonce
required

Any non-empty string; senders use 32 random hex characters. It isn’t checked for reuse.

string
timestamp
required

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.

string format: date-time
signature
required

Standard Base64 Ed25519 signature over envelope in RFC 8785 canonical JSON, made with the key in from_public_key_pem.

string

The envelope passed every check. status says what this instance did with it.

object
status
required

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.
string
Allowed values: accepted_pending completed ignored_duplicate
peer_id
required

The id of the receiver’s own row for the sender.

string format: uuid

The envelope failed one of the checks above, or it’s a confirm from an instance this instance hasn’t asked to pair.

object
error
required

Human-readable error summary

string
Example
the request could not be completed

This instance’s federation key isn’t available (see GET /federation/instance).

object
error
required

Human-readable error summary

string
Example
the request could not be completed