How to get a recovery key

A short tutorial to help those of us who are less technical. If you're familiar with JSON and can kinda navigate a command line, this is for you!

Update December 2024: Some other tools to do this!

• https://manual.renahlee.com/
• https://boat.kelinci.net's "Apply PLC operations"
• https://github.com/imax9000/bluesky-repo-backup (part of a backup service)

What is a recovery key and why might I want one?

When you do stuff on Bluesky, your data is stored by your PDS (Personal Data Server). It's like if all your posts/follows/etc. were in cloud storage like Box or Google Drive. By default, your PDS is managed by Bluesky, but you can change your PDS whenever you want (though it currently requires some technical knowledge).

But...what if Bluesky went evil and didn't want to cooperate? What if they wanted to keep you stuck using their storage?

That's where a recovery key comes in. A recovery key is like a password you can use to override whoever manages your PDS* and get back control of your account.

Since it's so powerful, you should keep it VERY, VERY SAFE.

*you can override whatever they did for up to 72 hours (3 days) after they did it

Overview

1. Logging in on the command line
2. Creating a key
3. Adding the key in your identity document
4. Adding a security token
5. Submitting your changes

Logging in on the command line

We'll be using the tool goat. You will need to have go installed, and then install goat with go install github.com/bluesky-social/indigo/cmd/goat@latest.

During the process, we'll be creating and using some files, so make sure your command line is in the folder you plan to put the files in.

You'll need your handle and password. (An App Password isn't allowed to request tokens.)

Log in with the command

goat account login --username <your handle> --app-password <your password>

Creating a key

Create a new cryptographic key by typing

goat crypto generate

It will print out a private key. This is the one you need to keep secret!

Just like how in real life, you'd have to add a lock to something for your key to be useful, we will need a counterpart to the private key. To get one, type

goat crypto inspect <the key you just got>

This will print out some information about the private key including its "Public (DID Key)".

Adding the key in your identity document

Search your handle on internect.info and copy your DID (Decentralized Identifier). This is your true ID which never changes even when you change your handle.

Now, look up your current identity document at https://plc.directory/<your DID>/log/last and copy it to a file. It's just JSON!

You can remove the sig and prev fields. It will look something like this:

{
  "type": "plc_operation",
  "services": {
    "atproto_pds": {
      "type": "AtprotoPersonalDataServer",
      "endpoint": "https://some.domain.here"
    }
  },
  "alsoKnownAs": [
    "at://your.handle.here"
  ],
  "rotationKeys": [
    "did:key:someExistingKeyIsHere"
  ],
  "verificationMethods": {
    "atproto": "did:key:someExistingKeyIsHere"
  }
}

Add your new key as the top entry of "rotationKeys". That way, it can override any keys below it, just like higher roles on Discord.

Adding a security token

Even though we made a new version of our identity document, the internet doesn't know about it yet. For security reasons, you'll need a token from email to upload your changes, so use the command

goat account plc request-token

and check your email for the token.

Add it to your identity document as "token". The document should now look something like this:

{
  "token": "<the token from your email>",
  "type": "plc_operation",
  "services": {
    "atproto_pds": {
      "type": "AtprotoPersonalDataServer",
      "endpoint": "https://some.domain.here"
    }
  },
  "alsoKnownAs": [
    "at://your.handle.here"
  ],
  "rotationKeys": [
    "<your new Public (DID Key)>",
    "did:key:someExistingKeyIsHere"
  ],
  "verificationMethods": {
    "atproto": "did:key:someExistingKeyIsHere"
  }
}

Submitting your changes

All that's left now is to upload it!

Sign the document with

goat account plc sign identity_document.json

This will print out your document, but with a new prev and sig added. Save it to a JSON file.

Now, submit the signed document with

goat account plc submit signed_identity_document.json

Congratulations! You've created a recovery key!

You can view it back on https://plc.directory/<your DID>/log/last.

Make sure to log out with goat account logout.

Ending notes

It should be noted that currently Bluesky PBC runs plc.directory. In the event that Bluesky nefariously blocks PLC updates, it would be difficult for everyone to agree on a new lookup. However, there are plans for plc.directory to be made independent.

Credits

Thanks to soopy.moe (🦋), mary.my.id (🦋), and goeo.lol (🦋) for walking me through this process!