Keyoxide is a privacy-friendly t1. ool to create and verify decentralized online identities.

Just like passports for real life identities, Keyoxide can be used to verify the online identity of people to make sure one is interacting with whom they are supposed to be and not imposters. Unlike real life passports, Keyoxide works with online identities or “personas”, meaning these identities can be anonymous and one can have multiple separate personas to protect their privacy, both online and in real life.

The tool helps you to verify your online profiles like GitHub, Mastodon, and others.

Here is my profile.

I used Bill Rawlinson’s guide as a reference.
During setup, I encountered some pitfalls. This article is an attempt to clarify and document the process by rewriting the original source.

In this article you’ll learn:

  • how to setup a GPG key and what to do to use it with keyoxide
  • how to verify your Mastodon, & GitHub account
  • how to setup a keyoxide account

What Do I Need?

Keyoxide is a weird beast.
It wasn’t clear to me how to get a keyoxide account.
Do I need to sign up somewhere?

The answer is: No, you don’t need to sign up for keyoxide.

But you need to create a GPG key pair and you need to upload it to

You’ll also need a valid email address.
This email address will be public on the Keyoxide website.

The GPG key pair needs a secure passphrase, so a password manager is recommended.

GPG Setup

First, we need GnuPGP on our local machine.

On macOs, you can install it via homebrew.

In your terminal, type:

brew install gnupg

Arch Linux (with yay):

yay -S gnupg

Create a Key Pair

Again, you need to use the terminal:


gpg --full-generate-key

(Arch) Linux:

gpg --full-gen-key
  • Choose RSA and RSA (option 1).
  • Keysize: 4096
  • Expiration date: 2y (2 years, you can extend the expiration)
  • Real name: you don’t need to use your real name, but this is the handle which will appear on your keyoxide side
  • email: use an email address that works and that you have access to (you can also add more email addresses later)
  • optional comment: leave blank
  • secure passphrase: use your password manager to create a password (and save it in your password manager together with the email address!)

You’ll be asked to generate some randomness, so you can move your cursor to help GPG to create your key.

Get Your Fingerprint

In your terminal, run the following command:

gpg -k

The answer will look like similar to this:

pub   rsa4096 2020-07-01 [SC]
uid           [ultimate] My name <valid@email.address>

Your keyoxide URL will be It will not work right now, but we’ll come back to it later.

I know, it is confusing.

More info on the Keyoxide website.

Add Your Accounts


For Mastodon, you’ll need to set profile metadata.

  1. go to your profile in Mastodon (https://<your instance url>/profile/settings/profile)
  2. edit your profile
  3. scroll down to “Profile metadata”
  4. add a label “keyoxide”
  5. as content add your keyoxide URL (

Read more about Mastodon on the keyoxide docs.


Create a new public GitHub gist.

Important: The file name must be!

The description for the file can be whatever you like.

As content for the file, add the following:

[Verifying my cryptographic key:openpgp4fpr:FINGERPRINT]

Here is my example Gist.

Read more about GitHub on the keyoxide docs.

Make a new blog post. The title does not matter, I chose “Keyoxide Proof” (see example).

The content of the post is the following:

[Verifying my keyoxide cryptographic key:]

Yes, it’s a public post which will look strange.

Add All Your Proofs to Your Gpg Key

Now we need to go back to the command-line.

gpg --edit-key YOUR_EMAIL_ADDRESS


gpg --edit-key FINGERPRINT

Replace with your email address.

This will open a command prompt.

  1. type: uid 1 (to select your user ID)
  2. type: notation
  3. enter the notation: (replace with your Gist URL)
  4. you will be asked for your passphrase, enter it now (you used a password manager, right?)
  5. repeat the process for your other accounts, type notation again
  6. enter the notation: (replace with your blog post URL)
  7. same again for all other accounts

For example, the notation for Mastodon is:


How to Show Your Notations for a Key?

gpg --edit-key FINGERPRINT

Show a list of user IDs to find the index, select it:

uid N # for example: uid 1

Show a list of notations:


How to Delete a Notation?

What happens if you made a mistake?

To delete an existing notation, you need to add it again, but with a minus symbol:


Upload Your GPG Key

Finally, you need to upload your public key to the

First, we’ll need to find a way to export our public key for upload. In your terminal, type the following:

gpg --armor --export YOUR_EMAIL_ADRESS > pubkey.asc

Replace with your email address. Don’t forget the greater than sign (>).

Open the OpenPGP website and upload the pubkey.asc.

Now you can go to your keyoxide URL and check if it works.
It might take a few minutes, but the process is reasonably fast.

What Happens if I Want to Add More Accounts?

If you later want to add more accounts, you can go through the process again.

First, find a way to way to create a proof, then edit the GPG key.
Upload the key.

Keyoxide will pick up the changes.

How Can I Export My Key Pair?

If you want to backup your key pair, you can read this article on how to export both the public and private key.