← Learn

Learn

Handles and DIDs: how Bluesky identity works

Every Bluesky account has two names. Its handle, such as alice.bsky.social, is a domain name that people read, and it can change. Its DID, such as did:plc:…, is a permanent identifier for software. Each one points to the other, and apps check both directions before they show a handle.

Last reviewed on November 14, 2026

On most social networks, your username is a row in one company's database. On Bluesky, an account's identity does not belong to any one server: it rests on two public names, which any app can check for itself.

Two names for one account

  • The handle is the name people read, such as alice.bsky.social. It is a domain name, and it can change. Apps often show it with an @ in front, but the @ is not part of the handle.
  • The DID (decentralized identifier) is the account's permanent ID, such as did:plc:ewvi7nxzyoun6zhxrhs64oiz. It is a W3C standard, made for software rather than for people, and it never changes.

The DID is the account's real identity. Apps resolve a handle to its DID, then use the DID everywhere. So when you change your handle, your posts and your followers stay with you; when you move to another PDS, your DID stays too. Data on the network is addressed by AT URIs, such as at://did:plc:…/app.bsky.feed.post/…: those written with the DID keep working after a change of handle.

did:plc and did:web

The DID standard allows many methods of creating and resolving identifiers. The AT Protocol supports two of them.

  • did:plc is the method made for the AT Protocol, developed by Bluesky Social PBC in 2022. The DID itself is the hash of the identity's first signed operation. Control of the identity rests with a few rotation keys: they sign every update, such as a new PDS address or a new signing key. The PLC directory collects these updates, serves the current state of each DID and keeps a public log of its history. If an update was wrong or hostile, a higher-priority rotation key can undo it within a recovery window, 72 hours today. It does not use any blockchain.
  • did:web is tied to a domain name: did:web:example.com is published over HTTPS by example.com. It is simple, but it offers no way to move to another domain, and no recovery if you lose control of the domain. The AT Protocol only accepts it for a whole hostname, not a path. It suits someone who is confident they will keep their domain.

did:plc is the more widely used of the two, and the one that survives losing a server or a domain, thanks to its rotation keys and its recovery window.

Going deeper. Anyone can read a did:plc from the directory: https://plc.directory/<did> returns its current DID document, and https://plc.directory/<did>/log/audit its history.

The DID document

Resolving a DID gives a small JSON document, the DID document. For the AT Protocol, three things in it matter:

  1. the handle the account claims, under alsoKnownAs, written as at:// followed by the handle;
  2. the account's public signing key, which checks the signatures of its repository, under the #atproto entry;
  3. the address of its PDS, under the #atproto_pds service.

A shortened example:

json
{
  "id": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
  "alsoKnownAs": ["at://alice.example.com"],
  "verificationMethod": [{ "id": "did:plc:ewvi7nxzyoun6zhxrhs64oiz#atproto", "type": "Multikey" }],
  "service": [{ "id": "#atproto_pds", "type": "AtprotoPersonalDataServer", "serviceEndpoint": "https://pds.example.com" }]
}

The signing key only signs the account's data. With did:plc, it has no control over the identity unless it is also one of the rotation keys, and keeping the two apart is the recommended practice.

How a handle is verified

A handle is only trusted when the link works both ways: the handle points to the DID, and the DID document names the handle back. Otherwise, anybody could claim to be someone else's account.

  1. Handlealice.example.comA DNS record or a web file on the domain gives the DID.
  2. DIDdid:plc:ewvi7nxz…The permanent identifier. Resolving it gives the DID document.
  3. DID documentat://alice.example.comNames the handle back, with the PDS and the signing key.
  4. Both directions agreeApps show the handle. If they disagree, they show handle.invalid.
How a handle is verified: the handle gives the DID, the DID gives its document, and the document names the handle back. Apps show the handle only when both directions agree.

The handle points to its DID in one of two ways:

  1. A DNS record. A TXT record on _atproto. followed by the handle, with the value did= followed by the DID. This is the recommended way for a single handle.
  2. A web file. An HTTPS request to /.well-known/atproto-did on the handle's domain returns the DID, as plain text and nothing else. This way is meant for services that host many handles and cannot add a DNS record for each.
text
_atproto.alice.example.com  TXT  "did=did:plc:ewvi7nxzyoun6zhxrhs64oiz"
text
GET https://alice.example.com/.well-known/atproto-did

did:plc:ewvi7nxzyoun6zhxrhs64oiz

When the two directions no longer agree, for example because the record or the file is gone, apps show handle.invalid instead of the handle. The account keeps its DID, its posts and its followers; it needs a handle that verifies again.

Use your own domain

Any domain or subdomain you control can be your handle: in the Bluesky app, choose to use your own domain, add the DNS record it shows with your DID, then confirm. Bluesky's own guide to domain handles walks through the steps, and the options for a custom handle are compared in our guides. Your last .bsky.social handle stays reserved for you.

A domain handle links your account to your website, which is why Bluesky calls it a form of verification. It is not the blue verification badge, a separate system Bluesky introduced in April 2025.

The rules of a handle

  • Only ASCII letters, digits and hyphens, in parts separated by dots, with at least two parts.
  • Each part is 1 to 63 characters long and cannot start or end with a hyphen; the last part, the top-level domain, cannot start with a digit.
  • The whole handle is at most 253 characters, and in practice 244, so that the name of its _atproto. DNS record still fits.
  • Handles are not case-sensitive: apps store and show them in lowercase.
  • Some top-level domains are refused, such as .local, .onion, .internal, .localhost, .arpa, .example, .invalid and .alt.

A service that gives out handles under its own domain may add its own rules, such as a minimum length or reserved words.

How Bluesky.bot uses this

Bluesky.bot uses the web file method. Every name.bluesky.bot handle answers /.well-known/atproto-did with its bot's DID, and once the bot switches to it, the bot's DID document names name.bluesky.bot back. Before a bot shows Live on Bluesky, Bluesky.bot asks Bluesky's public API whether both directions agree. How a bot is verified.

Frequently asked questions

How do I find my DID?
Your DID is public. In the Bluesky app, the screen for using your own domain as your handle shows it, in the DNS record it asks you to add (did=did:plc:…). Developers can resolve any handle to its DID with com.atproto.identity.resolveHandle, and look up a did:plc in the PLC directory.
What happens to my DID if I change my handle?
Nothing: your DID stays the same, and so do your posts and your followers. Mentions of your old handle still lead to your account. Only the readable name changes, and the new handle has to be verified in both directions.
What does handle.invalid mean?
Apps show handle.invalid when an account's handle and its DID no longer confirm each other, for example when the DNS record or the web file that proved the handle is gone. The account keeps its DID, its posts and its followers; it needs a handle that verifies again.

Sources

The official pages this explanation relies on. They are in English.

Give your bot a recognisable handle

Bluesky.bot gives bot accounts a free name.bluesky.bot handle, proven to the whole network, and a place in the public bot directory.