When you set up a custom domain handle on Bluesky, you must choose between two decentralized identifier methods: did:plc and did:web. Bluesky assigns did:plc automatically when you create an account, but you can switch to did:web if you want full control over your identity through your own domain. The wrong choice can lock you into a provider or make migration harder than necessary. This article explains the technical differences between did:plc and did:web, why each exists, and which one fits your use case best.
Key Takeaways: Bluesky did:plc vs did:web Handle Decision
- did:plc (default): Managed by Bluesky servers; supports account migration with a single click.
- did:web (custom domain): Hosted on your own web server; gives you full identity control but requires DNS and HTTPS setup.
- Settings > Account > Handle > I have my own domain: Where you choose did:web by entering your domain and placing a well-known file.
What Are did:plc and did:web on Bluesky?
A decentralized identifier or DID is a permanent, globally unique ID that Bluesky uses to link your account to your handle. Unlike a regular username that a platform owns, a DID stays with you even if you change your handle or move to another service. Bluesky supports two DID methods: did:plc and did:web.
did:plc is the default method. Bluesky runs a PLC directory server that issues and stores your DID. The server also handles key rotation and account migration. When you switch your handle to a custom domain, Bluesky still uses did:plc internally unless you specifically configure did:web. Most users never need to think about this because did:plc works transparently.
did:web is a newer method where your DID document lives on your own web server at a well-known URL. You control the document content, including the public keys that prove your identity. Bluesky verifies your handle by fetching the DID document from your domain. If you ever leave Bluesky, you can point your did:web document to a different service and keep your identity intact.
How did:plc Works
The PLC directory server assigns a random identifier like did:plc:abc123. The server stores your DID document, which contains your current public keys and a list of previous handles. When you migrate your account to a different Bluesky provider, the PLC server updates the document. Other services discover your DID by querying the PLC directory.
How did:web Works
Your DID becomes did:web:example.com. Bluesky expects a JSON file at https://example.com/.well-known/did.json. That file must contain your public key and a service endpoint pointing to the Bluesky PDS. You must host that file on a web server that supports HTTPS. Bluesky does not control your DID document; you do.
Steps to Switch Between did:plc and did:web
The decision to use did:web requires a one-time configuration. You cannot switch back to did:plc after setting did:web unless you remove the custom domain handle entirely. Follow these steps carefully.
Prerequisites for did:web
- A domain name you own and can modify DNS records for.
- A web server that supports HTTPS with a valid TLS certificate.
- Ability to create a file at the path .well-known/did.json on your server.
Step-by-Step: Configure did:web on Bluesky
- Get your Bluesky DID
Open Bluesky Settings > Account > Handle. Note the current handle and the DID string listed below it. You need this DID to build the JSON file. - Create the DID document
On your web server, create a file named did.json inside the .well-known directory. The file must contain your DID, one public key in JWK format, and a service endpoint for the Bluesky PDS. Use the official Bluesky documentation to generate the correct JSON structure. - Upload the file and verify HTTPS
Upload did.json to https://yourdomain.com/.well-known/did.json. Confirm the file is accessible over HTTPS and returns a 200 status code. Bluesky will reject the file if the server returns a redirect or an error. - Change your handle to the domain
In Bluesky Settings > Account > Handle, select I have my own domain. Enter your domain name exactly as it appears in the DID document. Bluesky verifies the did.json file and switches your handle to did:web. - Add DNS TXT record for verification (optional but recommended)
Create a TXT record at _atproto.yourdomain.com with the value did=did:web:yourdomain.com. This record helps other services discover your DID without fetching the JSON file every time.
Common Mistakes and Limitations
did.json File Returns a Redirect or Error
Bluesky requires the did.json file to be served directly from the exact path. If your web server redirects HTTP to HTTPS or adds a trailing slash, Bluesky fails verification. Use a static file server or configure your web server to serve the file without redirects. Test the URL with curl before changing your handle.
Public Key Format Mismatch
The DID document must include a public key in JWK format that matches the key Bluesky generated for your account. Copying the key from the wrong part of the Bluesky settings or using a key from another service breaks the verification. Use the exact JSON output from Bluesky’s developer tools or the official generator.
Cannot Use did:web with a Subdomain That Has No Server
If your domain uses a subdomain like user.example.com but you host the did.json file on the root domain example.com, Bluesky looks for the file at user.example.com/.well-known/did.json. You must host the file on the exact subdomain you use as your handle. You cannot redirect the subdomain to the root domain for this purpose.
did:web Does Not Support Automatic Migration
With did:plc, you can migrate your account to a different PDS provider by clicking a button in settings. With did:web, you must update the service endpoint in your did.json file manually. If you change providers, your followers may not see the update until they fetch the file again. Plan for this extra step if you anticipate moving servers.
Bluesky did:plc vs did:web: Feature Comparison
| Feature | did:plc | did:web |
|---|---|---|
| Setup effort | None; automatic on account creation | Requires web server and DNS configuration |
| Identity control | Managed by Bluesky PLC server | Fully controlled by domain owner |
| Account migration | One-click migration to another PDS | Manual update of did.json service endpoint |
| Portability to other platforms | Limited; other services must query PLC directory | Portable; same DID document can point to any AT Protocol service |
| Dependence on Bluesky | Requires Bluesky PLC directory to remain online | Independent; only needs your own server to serve the file |
| Technical knowledge required | None | Basic web server administration and JSON editing |
Bluesky users who want the simplest experience should stick with did:plc. Users who own a domain and want full identity sovereignty should configure did:web. The trade-off is convenience versus control.
You can now choose between did:plc and did:web based on your technical comfort and need for portability. If you value quick account migration and no server maintenance, did:plc remains the better option. If you run your own infrastructure and want your identity to outlive any single provider, set up did:web. After switching to did:web, verify your handle by checking the blue checkmark next to your domain in your profile. For advanced users, consider adding the DNS TXT record to speed up discovery by other AT Protocol clients.