2 min read

Making your own Mastodon Handle

Mastodon is popular right now, stand out from the crowd with your own Mastodon handle! Learn how I created my own @[email protected] handle.
Making your own Mastodon Handle
Photo by Battenhall / Unsplash

As any technology geek I decided to switch to Mastodon! Why would you ask? Well, several reasons prompted this switch:

  • Twitter is increasingly adding pay-to-use features (verification, prioritized answers, ...)
  • Twitter always had a huge amount of bots on the platform, continuously spamming my account

So, I wanted to go to Mastodon but use my personal handle: @[email protected] instead of the @[email protected] one I am on now. Luckily for us, this is possible through WebFinger and the /.well-known/webfinger endpoint which is used to discover information about people or other entities.

WebFinger Configuration

To configure the WebFinger spec, we should set-up the /.well-known/webfinger route that we can query and return a JSON response back.

For Mastodon, we should be able to query /.well-known/webfinger?resource=acct:[email protected] that will return a JSON file containing information about our profile. Let's fire up the URL https://fosstodon.org/.well-known/webfinger?resource=acct:[email protected] which returns:

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

To get our own handle working and discoverable, we can simply copy this file to our server and we should then be able to look for our handle! (e.g., @[email protected])

Using WebFinger on Ghost

For my personal website I am using Ghost, so how can we add the /.well-known/webfinger route here as well. Simply go to your theme and open up the routes.yaml file.

In there, add a route named /.well-known/webfinger that points to a handlebars file containing the JSON from above.

    content_type: application/json
    template: well-known/webfinger

Finally, create the handlebars file under ./well-known/webfinger.hbs


We are now able to use our own custom handle on Mastodon! Through the WebFinger spec, Mastodon instances will query this profile for more information and will know where to go towards.

Extra: If you want to add a link to your mastodon profile for verification, check out https://ghost.org/tutorials/add-social-media-icons/