Translate `user@domain` mentions to actor profile URIs.
What is WebFinger, and why is it used?
On Mastodon, user profiles can be hosted either locally on the same website as yours, or remotely on a completely different website. The same username may be used on a different domain. Therefore, a Mastodon user’s full mention consists of both the username and the domain, in the form
@username@domain. In practical terms,
@email@example.com is not the same as
@firstname.lastname@example.org. If the domain is not included, Mastodon will try to find a local user named
@username. However, in order to deliver to someone over ActivityPub, the
@username@domain mention is not enough – mentions must be translated to an HTTPS URI first, so that the remote actor’s inbox and outbox can be found.
Enter WebFinger. WebFinger as described in RFC 7033 is a spec that defines a method for resolving links to a resource, given only a URI on a particular server. This allows anyone to look up where a resource is located without having to know its exact location beforehand; for example, by email or phone number. This lookup is directed at the endpoint
/.well-known/webfinger, and a
resource query parameter is passed along with the lookup. The resource URI used with Mastodon is the
acct: URI as described in RFC 7565, with the username of a profile that is hosted on a particular domain.
username@domainaddress, but Mastodon’s internal logic depends almost completely on
acct: URIs or
username@domainrepresentations. Searching for any objects or profiles from an ActivityPub implementation without WebFinger will fail because the author cannot be converted to a user in the local database.
Sample WebFinger flow
Suppose we want to lookup the user
@Gargron hosted on the
Simply make a request to that domain’s
/.well-known/webfinger endpoint, with the
resource query parameter set to an
You can parse this JSON response to find a link with your desired type. For ActivityPub
id, we are interested in finding
This way, we have translated
https://mastodon.social/users/Gargron and we can now interact over ActivityPub by referring to this URI as
id where appropriate.
Note in the above example that
social.example does not use the same URI structure as Mastodon. Thus, we cannot simply guess the actor
id given only the username and domain. However, if
social.example supports WebFinger, then we can get this
idsimply by requesting
https://social.example/.well-known/webfinger?resource=acct:email@example.com parsing the response for a link with the
Last updated January 12, 2020 · Improve this page