Your Domain As Your Bluesky Handle, No DNS Needed
Jake MarshThis blog has a Bluesky account now, and its handle is the domain: @deallocatedobjects.com. The usual instructions tell you to add a DNS TXT record. I didn’t add one. Bluesky has a second way to prove you own a domain, and it’s one file on your web server, which for a static site like this one is the easier place to make a change.
The Steps#
I made the account with a temporary handle, deallocatedobjects.bsky.social. Then in Bluesky’s Settings, under Account and Handle, I picked “I have my own domain” and typed deallocatedobjects.com. That screen has two tabs, DNS Panel and No DNS Panel. No DNS Panel says to upload a text file to https://deallocatedobjects.com/.well-known/atproto-did containing the account’s DID, which it shows you with a copy button.
The site is a static build, so I put the DID in content/atproto-did.txt and had the build write it out:
if (existsSync(join(repo, "content/atproto-did.txt"))) {
const did = (await Bun.file(join(repo, "content/atproto-did.txt")).text()).trim();
if (/^did:[a-z]+:[A-Za-z0-9._:-]+$/.test(did)) await write(".well-known/atproto-did", did);
}The file has no extension, so nginx would guess its type. One line pins it:
location = /.well-known/atproto-did { types { } default_type text/plain; }After a deploy I pressed Verify Text File, then Update to deallocatedobjects.com. That button calls com.atproto.identity.updateHandle on the account’s server, which checks the handle and updates the account’s DID document.
Checking It With Curl#
Everything here is public, so you can check each piece without logging in. The file first:
$ curl -i https://deallocatedobjects.com/.well-known/atproto-did
HTTP/2 200
content-type: text/plain; charset=utf-8
content-length: 32
did:plc:zkms7f37vt7cen6jakhxjrfk32 bytes, exactly the DID. The text file in the repo ends with a newline and the .trim() in the build drops it.
Then ask Bluesky’s public API what the handle points to:
$ curl 'https://public.api.bsky.app/xrpc/com.atproto.identity.resolveHandle?handle=deallocatedobjects.com'
{"did":"did:plc:zkms7f37vt7cen6jakhxjrfk"}That’s one direction. The other is the DID document, which lives at the PLC directory and has to name the handle back:
$ curl https://plc.directory/did:plc:zkms7f37vt7cen6jakhxjrfk
{ ..., "alsoKnownAs": ["at://deallocatedobjects.com"], ... }The spec requires both. A handle only counts when it resolves to the DID and the DID document claims the handle, otherwise anyone could point their domain at someone else’s account. The directory’s audit log (/log/audit on the same URL) shows the two versions: the first, from account creation, has at://deallocatedobjects.bsky.social, and the second, 32 minutes later, has at://deallocatedobjects.com.
Last, the profile itself:
$ curl 'https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=deallocatedobjects.com'
{"did":"did:plc:zkms7f37vt7cen6jakhxjrfk","handle":"deallocatedobjects.com","displayName":"Deallocated Objects", ...}DNS Or The File#
The handle spec calls the DNS TXT record “the recommended and preferred resolution method for individual handle configuration”. It’s a record on _atproto.yourdomain.com with the value did= followed by the DID. The spec says the HTTPS method is meant for large services that can’t create thousands of DNS records, and it also covers handles so long that the _atproto. prefix would push the name past DNS’s 253 character limit.
I’d use DNS when you can get to it easily. It keeps working if you change web hosts, and it doesn’t depend on your web server staying up. The file makes sense when the web server is the easy part, like here, or when one server needs to answer for many handles.
If you have both and they disagree, resolvers are told to prefer the DNS answer. So a stale TXT record can quietly beat your new file.
Gotchas#
The body should be the DID and nothing else. The spec says servers shouldn’t add whitespace around it, though clients should strip a little. Bluesky’s app shows a “Wrong DID returned from server” error when the file holds a different account’s DID.
It has to be HTTPS on port 443 at the exact handle host. For a handle like blog.example.com, the file goes on blog.example.com, and a copy on www. or over plain http:// doesn’t count. Redirects are allowed “up to a reasonable number of redirect hops”, so a host that forwards somewhere else still works, but I keep the file answering with a 200 right at the apex.
The spec says the content type “does not need to be strictly verified”, but serving text/plain costs nothing.
Watch for a build that drops the file. Mine only writes it when the DID matches that regex, so a typo in the text file would ship a site with no atproto-did and no error.
If the file goes away, the handle stops resolving. The spec says the account’s handle should then be marked invalid, shown as handle.invalid, and the account’s server may stop accepting new posts until it verifies again. Other services should keep showing the posts. The DID never changes, so fixing the file brings it all back.
The old bsky.social handle doesn’t come along. The app says it stays reserved for you and you can switch back to it, but right now resolveHandle on deallocatedobjects.bsky.social returns “Unable to resolve handle”.