0017 API key plaintext format

Summary

This RFC proposes one plaintext format for all Unkey-generated API keys, including customer API keys and Unkey root keys. Imported and existing keys retain their original plaintext. This RFC supersedes the proposal in the historical key shape RFC.

Motivation

The currently generated keys are not unkey-branded in a way that would let us write a regular expression to detect them in source control systems. This only works for root keys right now, as they have a constant unkey_ prefix, but it does not work for our customer’s keys.

Detailed design

Format

The general grammar is as follows. [x] indicates the number of characters.

{prefix[1-7]}_{random[8]}unkeyv{version[1]}{depending on the version}

Version numbering starts at 1. The version occupies one Base58 character and
increments in Base58 alphabet order. It must appear before every version-dependent
field, so a parser can select the payload definition before reading its lengths. I do not like the fact, that the version is not at the very beginning or very end of the key. That would make parsing and versioning it simpler.
But the version is - by design - not random and if it’s part of the shown data (first 4 chars or 4 last chars) it doesn’t help users to see a difference between keys.

// bad because you can't visually scan the prefix and figure out what's what
sk_unke...131f 
sk_unke...0ann


// bad because you can't visually scan the suffix and figure out what's what
sk_9agx...eyv1 
sk_Z0Lk...eyv1

I chose to put it after 8 chars of randomness. This works, but also means that this is now fixed for eternity. A new format must also embed its version after the first 8 random chars, otherwise we couldn’t parse a key reliably if we ever wanted to. In reality this is probably fine, I do not foresee a reason to parse a key’s version other than to figure out if it has a checksum, and since we allow users to import their own keys, we’d never be able to do this for their keys anyways. But I would like to reserve the option…

Version 1

Version 1 has this exact shape:

{prefix[1-7]}_{random[8]}unkeyv1{random[36]}{checksum[6]}

Field	Length	Contents
Prefix	1–7	User controlled prefix
Separator	1	`_`
Random head	8	First part of the random value
Marker and version	7	Literal `unkeyv1`
Random tail	36	Rest of the random value
Checksum	6	Fixed-width Base58 CRC-32C

The complete key is between 59 and 65 characters. It provides 256 random bits (as recommended by NIST) and base58 encodes that into 44 characters, split into an 8 char and a 36 char section. Prefixes, markers, and checksums add no entropy.

Prefix

Prefixes must match:

^[A-Za-z0-9_]{0,6}[A-Za-z0-9]$

They contain one through seven ASCII letters, numbers, or underscores, and must end in an alphanumeric character. prod_sk, pk_live, and unkey are valid. prod_sk_ or eight-character prefixes are invalid.

Checksum

GitHub recommends adding a checksum, so we can pre-filter false positives without a database lookup. We calculate a CRC-32 checksum over the complete key up to, but excluding, the checksum:

unsigned_key   = prefix + "_" + random_head + "unkeyv1" + random_tail
checksum_value = CRC-32C(ASCII(unsigned_key))
checksum_text  = base58Fixed(checksum_value, 6)
key            = unsigned_key + checksum_text

GitHub secret scanning

The version 1 regex for github is:

[A-Za-z0-9_]{0,6}[A-Za-z0-9]_[1-9A-HJ-NP-Za-km-z]{8}unkeyv1[1-9A-HJ-NP-Za-km-z]{42}

Legacy root keys keep their existing GitHub pattern. Either we can provide 2 expressions, or we just merge them for one mega-cursed one.

Database changes

Separately I do want to change how we display keys in our dashboard. I think it would be nice to show not only the first 4 chars, but also the last 4. This just helps to visually discriminate between two keys when looking at them at a glance. To do that, we’d store the prefix, first four random characters, and final four characters for newly generated keys:

prefix = "prod_sk"
start  = "K7pQ"
end    = "X2Ks"

And then display them as prod_sk_K7pQ...X2Ks. Existing non-recoverable keys cannot backfill end. Legacy rows keep their existing start, and use "" for empty fields. Storing the prefix like this, also makes it easier to reroll keys, cause we don’t have to parse the key to figure out what the prefix should be.

Deprecating configurable lengths

We should remove the option to choose a custom length and just follow the NIST recommendation of 256 bits of entropy. There’s no good reason for us to allow a user to use less and having fewer (mostly irrelevant) config options is always good in my opinion.

Drawbacks

New keys are a little longer.

Alternatives

Put unkeyv1 at the beginning: easier to scan, but customer keys become harder to distinguish visually and appear Unkey-branded.
Put the version at the end: keeps the body visually clean, but a parser cannot know version-dependent payload and checksum lengths before reaching it.
Omit the checksum: shortens keys, but always requires database lookups for secret scanning false positives.

Overview

Services

RFCs

0017 API key plaintext format

Summary

Motivation

Detailed design

Format

Version 1

Prefix

Checksum

GitHub secret scanning

Database changes

Deprecating configurable lengths

Drawbacks

Alternatives

​Summary

​Motivation

​Detailed design

​Format

​Version 1

​Prefix

​Checksum

​GitHub secret scanning

​Database changes

​Deprecating configurable lengths

​Drawbacks

​Alternatives

Summary

Motivation

Detailed design

Format

Version 1

Prefix

Checksum

GitHub secret scanning

Database changes

Deprecating configurable lengths

Drawbacks

Alternatives