Aaron Parecki

I recently got access to the BlueSky beta, and decided to poke around to see what it's all about. I will save the details of what it is and how I feel about it for a different post. However, one of the first things you do when you sign up is choose a username that exists under the bsky.app domain. I have zero interest in another name rush where everyone tries to claim the shortest username possible, so I went with aaronpk.bsky.app rather than trying to get a or apk.

But, as I was poking around the app and replying to a few people, it just didn't feel like "me" yet. I don't care about renting a name in someone else's space. Yesterday, Jay Graber posted on the BlueSky blog all about supporting custom domains as identities in BlueSky. Naturally I was curious to try this out myself, but there were no technical details available in the blog post.

When I opened my BlueSky timeline, I saw a few people mentioning that they had figured out how to do it even before the app supported it natively. I did some digging around, and jik pointed me to the right places in the AT Proto docs, and I was able to change my handle to aaronpk.com!

Below are the instructions for how to do this yourself. Please note that these instructions will be made obsolete in a week or two since the BlueSky developers are planning on shipping first class support for custom domains in the app and you won't need to do this workaround for long.

Overview

The rough process for this is:

• Create a DNS TXT record on your domain with the value of your underlying BlueSky ID
• Get a token for your account (e.g. "log in" to your account from an HTTP client)
• Update your profile with your new domain

Note: To make these POST requests, you'll need an HTTP client that can POST in JSON format. You can use cURL, httpie, Postman, or write code in whatever language you want. I'll use httpie for the examples.

Get a token for your account

First, you need to "log in" to your account. This process will return an access token you can use to update your profile. Logging in will also tell you your DID, the unique identifier for your underlying account. (The "handle" on your account is more like a display name, and that's how your account can end up being portable across domains as well as BlueSky servers later.)

Call the com.atproto.server.createSession method with your email and password you used to sign up. (Type this all on one line, I've just split it into multiple lines for readability. Also, again, if you're using cURL or another HTTP client, make sure you send this payload as JSON, not form-encoded.)

http post https://bsky.social/xrpc/com.atproto.server.createSession
            identifier=user@example.com password=hunter2

The response will be a JSON document with your access token as well as DID:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 609
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Mar 2023 15:29:38 GMT
ETag: W/"261-15oNf47+gL0kDnvlsvzpUK0ocx8"
X-Powered-By: Express

{
    "accessJwt": "eyJh...",
    "did": "did:plc:s2koow7r6t7tozgd4slc3dsg",
    "handle": "aaronpk.bsky.app",
    "email": "aaron@parecki.com",
    "refreshJwt": "eyJh..."
}

Create a DNS Record

Go to your domain registrar and create a new TXT record on your domain.

• Subdomain: _atproto
• Value: did=did:plc:XXXXXXXXX
• TTL: Default

In my case, the domain I wanted to use is aaronpk.com, so I would create a new subdomain _atproto.aaronpk.com, with the value did=did:plc:s2koow7r6t7tozgd4slc3dsg.

_atproto.aaronpk.com TXT did=did:plc:s2koow7r6t7tozgd4slc3dsg

Update your Profile

Wait a little while to make sure the DNS entry takes effect. Then you can update your profile with your new domain by running the com.atproto.identity.updateHandle method.

Use the value of the accessJwt you got from the first request. (Again, type this out all on one line.)

http post https://bsky.social/xrpc/com.atproto.identity.updateHandle 
      Authorization:"Bearer eyJ..." 
      handle=aaronpk.com 

You won't see a response, but that means it worked! Next time you open the app, you'll probably see a bunch of errors. So log out of the app, and log back in! Right now, you'll need to use your email address to log in instead of your handle, but they are going to fix that in a future update.

Now you should see your new domain as your handle in the BlueSky app!

Once again, this will all be obsolete once they ship this feature in the app itself! Here's a sneak peek from Paul of what the interface will look like!

More Fun

Once you've got this far, you can start to use the API for some other fun things!