"My adventure in designing API keys" — a practical primer on prefixes, checksums and shard routing

What the author found

It has been reported that a developer turned product engineer published a hands-on blog about API key design after finding surprisingly little practical guidance online. The post walks through the familiar — prefixes, random hex payloads, and checksums — but doesn’t stop at theory. The writer says they dug in because a blunt answer ("it’s just a string") felt unsatisfying. Curiosity won. Good news: the write-up reads like someone who built it, tested it, and then explained what worked and why.

Format, storage and small but important details

The blog outlines the now-common pattern: a human-friendly prefix (think GitHub’s gh* or Stripe’s sk_live/sk_test), a random hex section, and often a trailing checksum to catch typos before you hammer the database. It has been reported that the checksum purpose is precisely that — a cheap validation step akin to credit-card checks before a DB lookup. The author also notes standard safety practices: keys are hashed and stored server-side, shown once at creation, and many systems save only the first few characters for UX (so you can tell keys apart). Permissions, per-key logging, and simple UX choices matter as much as cryptography here.

The sharding headache and some pragmatic fixes

The emotional heart of the piece is a real engineering snag: routing a public API call to the correct tenant shard when you no longer have session cookies with account IDs. The default, the author says, was to hash the API key and map that to an account ID — this worked reasonably well in tests (it has been reported that reads/writes held up near ~20 million records). But why store an entire hash if you only need to identify the account? One clever workaround described: give each tenant a unique prefix embedded in the key so the first bytes indicate the owner and therefore the shard. Simple, sensible, and fast — though not without trade-offs around information leakage and management of prefix space.

Why this matters

APIs are everywhere, and small design choices ripple into security, latency and operational complexity. The blog is a quick reminder that engineering is often a series of trade-offs: hash-everything for uniformity, or bake routing hints into the key for speed. Which side you land on? That depends on scale, threat model, and taste. Want a neat, practical read grounded in tests rather than ivory-tower theory? This one’s worth a look.

Sources: vjay15.github.io, Hacker News