Bernhard Bock

Mastodon alias on your own domain with WebFinger

Finally, I’m making the jump from Twitter to Mastodon. At the moment, I don’t feel running my own Mastodon instance is worth the hassle. There are plenty of free Mastodon instances out there which offer free accounts. However, I do expect some churn in the future as instances are shut down and new instances appear.

While exporting / importing followers works, and there’s even a mechanism for forwarding to a new server, I do not feel comfortable distributing a handle like I’d like to have my handle on my own domain, which I have full control over.


Enter Webfinger. Webfinger is a standardized method to resolve http links to a resource, and it is supported by Mastodon.

If you use a handle like, Mastodon does a lookup at the endpoint /.well-known/webfinger, with the user part as query parameter:

It expexts to get back a JSON response (called a “JSON Resource Descriptor”) with multiple details on the user account. Apart from the activitypub feed (Mastodon), you can add a profile page and other details if you want.

At the moment, I only add the activitypub feed, as I am not aware of any other application making use of Webfinger.

  "subject": "",
  "aliases": [""],
  "links": [
      "rel": "self",
      "type": "application/activity+json",
      "href": ""

More details can be found in the Mastodon documentation.


With this simple JSON endpoint set up, you can now search for on any Mastodon instance and find my current profile. If I ever switch servers, I can just update this JSON and point it to my new account.

Screenshot of Mastodon search

Unfortunately, after the initial search, this abstraction breaks: If you choose to follow me, you’ll follow the resolved account (currently and I need the server to redirect you in future.

Still, for printing the handle on presentations, documents etc., this is actually helpful. And maybe, in future you can actually keep the abstraction alive beyond just the first search.

— Feb 3, 2023