/.well-known/webfinger

What it is

WebFinger is a discovery protocol defined in RFC 7033. A client asks /.well-known/webfinger for information about a resource identifier — typically an account in the form acct:user@example.com — and the server returns a JSON Resource Descriptor (JRD) describing that resource and where to find more.

It is the protocol that lets you type @alice@mastodon.example into any Fediverse client and have it resolve to Alice's ActivityPub profile, regardless of which server she lives on.

Why it matters

• Federation depends on it. Mastodon, Pleroma, Misskey, GoToSocial, PeerTube, Lemmy and every other ActivityPub-speaking platform use WebFinger as step one of "who is this user".
• It abstracts the URL. A handle like acct:joost@example.com is human-friendly. The actual ActivityPub actor URL might be https://example.com/users/joost. WebFinger maps one to the other.
• It works across protocols. WebFinger is not tied to ActivityPub. It can advertise any kind of link relation for any kind of resource.

If your site does not host accounts that need to federate, you do not need this URL.

How to implement

Accept GET requests with a resource query parameter. Return application/jrd+json.

GET /.well-known/webfinger?resource=acct:joost@example.com HTTP/1.1
Host: example.com
Accept: application/jrd+json

A typical response for a Fediverse account:

{
  "subject": "acct:joost@example.com",
  "aliases": [
    "https://example.com/@joost",
    "https://example.com/users/joost"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@joost"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://example.com/users/joost"
    }
  ]
}

Rules:

• Serve over HTTPS, and respond on the host that matches the right-hand side of the acct: URI. A query for joost@example.com must be answered by example.com, not social.example.com.
• Return 404 for unknown resources, 400 for a missing or malformed resource parameter.
• Accept the rel query parameter and filter the links array accordingly. Clients use it to reduce payload size.
• Set permissive Access-Control-Allow-Origin: * so browser-based clients can fetch the response.

Common mistakes

• Answering on the wrong host. If user identifiers look like @alice@example.com but WebFinger lives on social.example.com, federation breaks. Fix this by serving WebFinger from example.com and redirecting or proxying as needed.
• Returning text/plain or application/json instead of application/jrd+json.
• Leaking the existence of accounts via different responses for "user exists but private" and "user does not exist". Pick one behaviour and apply it consistently.
• Ignoring the rel filter and always returning every link.

Verification

curl -s "https://example.com/.well-known/webfinger?resource=acct:joost@example.com" | jq .

Then try to follow your account from a Mastodon server you do not control. If federation fails, WebFinger is almost always the first thing to check.