Example
This page describes a typical federation flow between two servers, a.social and b.social, in several different contexts.
All examples, domains, names and timestamps are fictional and are used for illustrative purposes only.
Some details have been slightly simplified for clarity.
Sending a Note
@alice on a.social creates a note with the following content:
Hello, @joe@b.social! How are you doing today?
@alice has mentioned @joe@b.social in the note.
Resolving the Mention
a.social resolves the mention by querying b.social for the user joe using WebFinger.
cURL example
curl https://b.social/.well-known/webfinger?resource=acct:joe@b.social -H "Accept: application/json"
b.social responds with the following JSON:
{
"subject": "acct:joe@b.social",
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://b.social/users/joe"
}
]
}
In a real Versia implementation, usernames would not be included in user profile's URL, as they can be changed. Instead, the id could be used.
This is done for simplicity in this example.
Fetching the User
a.social fetches the user profile of joe from b.social using the URL provided in the WebFinger response.
curl https://b.social/users/joe \
-H "Accept: application/json" \
-H "User-Agent: CoolServer/1.0 (https://coolserver.com)" \
# The request is signed by a.social's instance private key
-H "Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==" \
-H "Versia-Signed-By: https://a.social/users/alice" \
-H "Versia-Signed-At: 1729241687"
b.social responds with the following JSON:
{
"id": "bde22zi3ca8762",
"type": "User",
"uri": "https://b.social/users/joe",
"created_at": "2024-10-13T18:48:19Z",
"avatar": {
"image/webp": {
"content": "https://cdn.b.social/avatars/joe.webp",
"remote": true
}
},
"collections": {
"featured": "https://b.social/users/joe/featured",
"followers": "https://b.social/users/joe/followers",
"following": "https://b.social/users/joe/following",
"outbox": "https://b.social/users/joe/outbox"
},
"display_name": "Joe Swanson (Winter Arc :gigachad:)",
"inbox": "https://b.social/inbox",
"public_key": {
"actor": "https://b.social/users/joe",
"algorithm": "ed25519",
"key": "MCowBQYDK2VwAyEAOSCcfsde0Ya3vf/P6lzgK0pA8qCISqneaze3omLlQCQ="
},
"username": "joe",
"extensions": {
"pub.versia:custom_emojis": {
"emojis": [
{
"name": ":gigachad:",
"content": {
"image/png": {
"content": "https://cdn.b.social/emojis/gigachad.png",
"remote": true
}
}
}
]
}
},
}
a.social now has the user profile of joe and can display the note with the correct user information.
Serializing the Note
Finally, a.social serializes the note to send it to joe.
{
"id": "782addd9-c051-4eea-8ba4-23d561d0c5bb",
"type": "Note",
"uri": "https://a.social/notes/782addd9-c051-4eea-8ba4-23d561d0c5bb",
"created_at": "2024-12-01T12:19:06Z",
"author": "https://a.social/users/alice",
"category": "microblog",
"collections": {
"replies": "https://a.social/notes/782addd9-c051-4eea-8ba4-23d561d0c5bb/replies",
"quotes": "https://a.social/notes/782addd9-c051-4eea-8ba4-23d561d0c5bb/quotes"
},
"content": {
"text/html": {
"content": "Hello, <a class=\"u-url mention\" href=\"https://b.social/users/joe\">@joe@b.social</a>! How are you doing today?",
"remote": false,
},
"text/plain": {
"content": "Hello, @joe@b.social! How are you doing today?",
"remote": false,
}
},
"group": "public",
"mentions": [
"https://b.social/users/joe"
]
}
It is now time for a.social to send the note to joe.
Sending the Note
a.social sends the note to joe's inbox at b.social.
curl -X POST https://b.social/inbox \
-H "Content-Type: application/json; charset=utf-8" \
-H "Accept: application/json" \
-H "User-Agent: CoolerServer/1.0 (https://coolerserver.com)" \
# The request is signed by Alice's private key
-H "Versia-Signature: 9BrfplAPVH6OEqlV5eX7MazaZAInSCPODZcBEvMliBi/OwfbCAsezlb0O9jUX9ZcbBA68ThA4WUgS9V+42rfAQ==" \
-H "Versia-Signed-By: https://a.social/users/alice" \
-H "Versia-Signed-At: 1733051946"
b.social responds with a 202 Accepted status code.
Displaying the Note
The software on b.social processes the note and shows it to joe using whatever interface it has.
joe can now see the note from @alice on a.social and respond to it.