Generating API keys and secret tokens safely
An API key is a password for a program. Unlike a human password, nobody has to remember it, so it can be fully random and long. The hard parts are choosing the size, encoding it cleanly, and storing it so a database leak does not leak the keys.
Random key generator
Step 1: decide how many random bits
Strength comes from the number of random bits, not from the characters you see. 128 bits is already far beyond brute force. 256 bits is a common choice because it costs nothing extra and leaves a wide margin. Always take the bits from a cryptographic source: crypto.getRandomValues in a browser, crypto.randomBytes in Node.js, or the secrets module in Python. Never use Math.random() or a timestamp.
Step 2: pick an encoding
Random bytes are not printable, so they need an encoding. Each one changes the length but not the strength.
| Random bytes | Hex (4 bits per char) | base64url (6 bits per char) | base62 (about 5.95 bits per char) |
|---|---|---|---|
| 16 (128 bits) | 32 chars | 22 chars | 22 chars |
| 24 (192 bits) | 48 chars | 32 chars | 33 chars |
| 32 (256 bits) | 64 chars | 43 chars | 43 chars |
The base62 column comes from ceil(bits ÷ log2 62). For 256 bits: 256 ÷ 5.954 = 42.99, so 43 characters. Base62 uses only letters and digits, so a double-click selects the whole key, and no character needs escaping in a URL, a header or a shell.
Same bytes, two encodings. The nine bytes 00 01 02 FA FB FC FD FE FF are 000102fafbfcfdfeff in hex (18 characters) and AAEC-vv8_f7_ in base64url (12 characters).
The modulo bias trap
A common shortcut maps a random byte to a character with byte % 62. A byte has 256 values, and 256 = 4 × 62 + 8. Values 0–247 cover each character exactly 4 times, but the leftover values 248–255 give characters 0–7 a fifth chance. Those 8 characters then appear with probability 5/256 instead of 4/256, which makes them 25% more likely than the rest. The fix is rejection sampling: throw away any byte of 248 or more and draw again. The generator above does this. Hex and base64 avoid the problem, because 16 and 64 divide 256 exactly.
Step 3: add a prefix
Many services start keys with a short, readable tag such as live_ or test_. A prefix tells a person which environment a key belongs to, and it lets secret-scanning tools find keys that were pushed to a public repository by mistake. The prefix is not secret and adds no strength.
Step 4: store a hash, not the key
- Show the full key to the user once, at creation.
- Store a SHA-256 hash of the key, plus the first few characters so people can tell keys apart in a list.
- When a request arrives, hash the presented key and compare it with the stored hash using a constant-time comparison.
A fast hash is fine here, unlike passwords, because a 256-bit random key cannot be guessed no matter how fast the hash is.
Common mistakes
- Using a UUID as a key. A version 4 UUID has only 122 random bits and some libraries make other versions that are predictable. Generate a key for the purpose.
- Putting secret keys in front-end code. Anything shipped to a browser is public. Keep secret keys on the server, for example in an environment file.
- Keys that never expire. Support more than one active key per account so people can rotate without downtime.
Questions
Are the keys from this page safe to use?
They come from your browser’s cryptographic random source and are never sent or saved. Still, for production systems, generate keys in your own server code so they never pass through a web page.
Is a longer key always better?
Beyond 256 bits there is no practical gain. Very long keys only make headers and logs bulkier.