WebFinger JRD Builder (RFC 7033)

WebFinger and the JRD: how the Fediverse finds people

WebFinger is the discovery protocol defined by RFC 7033 (September 2013) that turns a human-friendly identifier — [email protected] — into a machine-readable description of where that user actually lives on the web. It is the substrate the Fediverse runs on: Mastodon, Pleroma, Pixelfed, GoToSocial, Misskey, Akkoma and the federated previews of Meta Threads all walk WebFinger to resolve @[email protected] before the first ActivityPub message can be delivered. Without WebFinger there is no federation.

A WebFinger response is a JRD (JSON Resource Descriptor) served from a fixed endpoint with a specific content type:

GET /.well-known/webfinger?resource=acct:[email protected] HTTP/1.1
Host: example.com
Accept: application/jrd+json

200 OK
Content-Type: application/jrd+json
Access-Control-Allow-Origin: *

{
  "subject": "acct:[email protected]",
  "aliases": [
    "https://example.com/@alice",
    "https://example.com/users/alice"
  ],
  "links": [
    { "rel": "self",
      "type": "application/activity+json",
      "href": "https://example.com/users/alice" },
    { "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@alice" },
    { "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://example.com/authorize_interaction?uri={uri}" }
  ]
}

The acct: scheme and the .well-known path

The acct: URI scheme (RFC 7565) was designed specifically for this — acct:[email protected] means "the account named alice at example.com" without committing to email, ActivityPub or any other protocol. The /.well-known/ path comes from RFC 8615; the WebFinger endpoint is one of the most-deployed entries there, alongside /.well-known/openid-configuration and /.well-known/security.txt. WebFinger replaces the legacy XML format XRD from OpenID 2.0 — the JSON-only shape is dramatically simpler to serve from a static file.

Mandatory link relations and CORS

For Fediverse interoperability the essential link relations are:

• self with application/activity+json — the ActivityPub actor URL
• http://webfinger.net/rel/profile-page — human-facing HTML profile
• http://ostatus.org/schema/1.0/subscribe — remote-follow template
• http://schemas.google.com/g/2010#updates-from — Atom feed (legacy OStatus)

CORS is non-optional: serve Access-Control-Allow-Origin: * or Fediverse web clients will fail silently. The endpoint must also accept a resource query parameter that may URL-encode the colon as %3A.

Operations, cache and privacy

Real instances cache WebFinger responses for hours — Cache-Control: max-age=3600 is typical. Mastodon rate-limits incoming requests aggressively (the Threads–Mastodon federation rollout in 2024 stressed this). Privacy concern: a public WebFinger endpoint confirms account existence — useful for legitimate discovery, but an enumeration surface for harassment. Some instances (sharkey, akkoma) allow authorized fetch: signed HTTP requests required even for WebFinger. The Brazilian Fediverse hubs (mastodon.com.br, ursal.zone, bolha.us) all expose standard WebFinger.

FAQ

Do I need WebFinger if I run an ActivityPub server? Yes. ActivityPub itself does not define name-to-actor lookup — WebFinger is the de-facto bridge between handles and actor URLs.

Can I disable WebFinger for privacy? Some instance software lets you require authentication (AUTHORIZED_FETCH=true). Disabling entirely breaks federation — you can be followed but only by people who already know the actor URL.

Why application/jrd+json and not plain application/json? RFC 7033 mandates the JRD media type — strict clients reject responses served as plain JSON.

Does Meta Threads use WebFinger? Yes — the Threads federation gateway exposes WebFinger for opted-in Threads accounts since 2024, returning ActivityPub self links.