WebFinger is an HTTP-based protocol that lets software look up information about a person or resource from an address like username@domain. Federated platforms use it to turn a handle into a link to the account’s profile and actor.
It is one small building block in any community platform that talks to other servers rather than living in a silo.
What WebFinger does
RFC 7033, published in September 2013 by the IETF, describes WebFinger as a protocol that “can be used to discover information about people or other entities on the Internet using standard HTTP methods.” In practice, that means one question: given an identifier, what does the server at that domain know about it?
An email-style handle such as [email protected] says nothing about where a profile lives or which URL speaks a federation protocol. WebFinger fills that gap. A client asks example.com about alice and gets back a small JSON document listing related links: a profile page, a machine-readable actor, perhaps a feed.
The protocol does not post messages, deliver notifications, or authenticate anyone. It only answers lookup questions, which is why it pairs with other protocols rather than replacing them. The differences between those larger protocols are covered in a comparison of activitypub vs atproto.
The idea resembles a phone directory run by each domain. Nobody needs a central registry, because the domain in the handle tells the client which server to ask. That is what makes the lookup work without a central authority, and it is the reason federated networks can grow without a single company holding the address book.
How a WebFinger request works
The request format is fixed. Per the RFC, “the path component of a WebFinger URI MUST be the well-known path /.well-known/webfinger”. The client adds a “resource” query parameter naming the thing it is asking about.
- The user types or pastes a handle, for example @[email protected].
- The client builds an acct: URI from it: acct:[email protected].
- It sends an HTTPS GET to the well-known path on example.com with that URI as the resource parameter.
- The server replies with a JSON Resource Descriptor (JRD), served as application/jrd+json.
- The client reads the links in the reply and follows the one it needs.
HTTPS is mandatory. The RFC states that “a client MUST query the WebFinger resource using HTTPS only,” and that on a certificate failure or error response the client must not retry over plain HTTP. In other words, a failed secure lookup stays failed; there is no quiet downgrade.
A client can also add a “rel” parameter to filter the response to one link relation type, which keeps replies small. The RFC’s example asks about acct:[email protected] for a single OpenID Connect issuer relation and receives just one link in return.
The RFC’s own examples show servers sending Access-Control-Allow-Origin: *, so browser-based JavaScript clients can read the response across origins.
Anatomy of the response
The JRD is a JSON object. Its main members are a “subject” (the identifier being described), optional “aliases” (other URIs for the same entity), optional “properties”, and a “links” array. Each link carries a “rel” value that says what it is, plus an “href” and often a “type”.
The Mastodon documentation shows a real-world response for acct:[email protected]. Its aliases include the profile address https://mastodon.social/@Gargron and the actor address https://mastodon.social/users/Gargron. Its links include one with the relation http://webfinger.net/rel/profile-page and type text/html, which points to the human-readable profile.
The same structure is not limited to people. The RFC also shows a query for a blog article, using the article’s own URL as the resource, and a reply that lists aliases and properties for that page. The acct: form is simply the one that federated social software standardised on.
WebFinger in the fediverse
ActivityPub servers rely on WebFinger to resolve handles. The Mastodon documentation says the resource URI it uses is “the acct: URI as described in RFC 7565, with the username of a profile that is hosted on a particular domain.”
The key link is the one with rel=”self”. Mastodon documents that it finds an actor’s ID by requesting the WebFinger URL and “parsing the response for a link with the application/ld+json; profile=”https://www.w3.org/ns/activitystreams” or application/activity+json type.” Once the client has that actor URL, ActivityPub takes over: it fetches the actor document, finds the inbox, and delivers activities.
Mastodon also applies checks. When given a handle, it builds the acct: URI, makes the request, and confirms that the subject is present and that a valid self link exists. Its documentation allows the actor to live on a different host from the handle, for example a handle at example.com pointing to an actor on ap.example.com, as long as the actor’s preferred username and the subject match the request.
That split is useful. A site owner can keep a short handle on their main domain while the software runs on a subdomain. It also explains why, for anyone setting up a self-hosted open source community platform, a misconfigured well-known path is a common reason a new account cannot be found from other servers.
Troubleshooting and practical cautions
Most discovery failures come from a short list of causes, and a plain HTTPS request to the well-known path from any terminal or browser will reveal most of them.
- Lookup only. A successful WebFinger reply proves that a server claims a link, not that the account is trustworthy.
- Exposure. Anything placed in a JRD is public to anyone who can query the domain. The RFC includes a section on user privacy considerations for this reason.
- Redirects and proxies. Reverse proxies and CDNs must pass the well-known path through unchanged, with a valid certificate. A broken certificate alone makes the lookup fail, since clients may not fall back to HTTP.
- Handle-to-actor consistency. Mismatches between the requested resource, the subject, and the actor’s username cause lookups to fail in strict implementations.
- Missing self link. A reply with a profile-page link but no self link of an ActivityPub type leaves a federation client with a web page and nothing to talk to.
When a new account cannot be found from another server, the order of checks is usually the same: confirm the certificate, request the well-known URL by hand, confirm the subject matches the handle, then confirm the self link points to an actor that answers.
Frequently asked questions
What is WebFinger used for?
It resolves an identifier such as an acct: URI into a JSON document of links, so a client can find a profile page or federation actor for that account.
Is WebFinger the same as ActivityPub?
No. WebFinger only handles discovery. ActivityPub is a separate protocol for fetching actors and exchanging activities once an actor URL is known.
Does WebFinger require HTTPS?
Yes. RFC 7033 says a client must query using HTTPS only and must not fall back to HTTP if the secure request fails.
Where does the request go?
To the path /.well-known/webfinger on the domain from the handle, with the resource query parameter set to the identifier.
