Making Beautiful API Keys

Original Article ↗ Hacker News Discussion ↗

Prefixes, IDs, and Metadata

  • Many commenters like fixed prefixes on API keys (e.g., company_, test_/live_):
    • Easier to recognize keys, distinguish environments, and debug user issues.
    • Helpful for secret scanning and leak detection.
  • Similar enthusiasm for prefixed resource IDs to avoid confusing different object types.
  • Some suggest appending human-readable metadata (e.g., expiry date) as a suffix.

Encoding, “Beauty,” and Readability

  • Base32-Crockford is praised for:
    • Avoiding ambiguous letters (I, L, O, sometimes U) and tolerant decoding (mapping O→0, I/L→1).
    • Being good for invite codes or things read aloud.
  • Others argue “beautiful” UUID-like keys are still just long random strings; not meaningfully easier to say or remember.
  • Some prefer different grouping (e.g., 5-character blocks) or word/phrase-based encodings instead of CD-key style.

Copying, Dashes, and UX

  • Strong pushback on dashes because they break double-click selection; easy copy-paste is the top priority for many.
  • A few are fine with dashes for visual comparison and suggest:
    • Allowing optional separators or using _.
    • Using UI tricks like user-select: all or copy buttons.
  • The article’s line about “not wanting users copying and pasting everywhere” is widely disliked; seen as paternalistic.

Security, Entropy, and UUID vs API Keys

  • Clarification that base32 vs hex is just an encoding; collisions and entropy are unchanged if mapping is 1:1.
  • One commenter notes shorter representation can mislead people into thinking entropy was reduced.
  • Separate discussion emphasizes:
    • API keys are secrets with permissions and revocation.
    • UUIDs are public identifiers, not security credentials.
  • Some question using timestamped UUIDv7 for keys at all, preferring purely random bits plus versioning and checksums.

Bikeshedding vs Product Value

  • Many see the key-format work as classic bikeshedding or misallocated startup energy; developers only copy keys once and rarely care how they look.
  • Others defend it as:
    • A trivial implementation that doubles as effective content marketing.
    • An example of caring about small UX details that create a “halo effect” for the product.
  • Some concerns that obsessing over IDs might signal misplaced priorities in other areas.

Alternatives and Ecosystem Notes

  • Mentioned alternatives include:
    • Prefix-based schemes with public/secret parts and base58.
    • TypeID-style prefixed IDs, ULID Postgres extensions, and URL-based API keys.
  • Skepticism about pulling in tiny JS libraries (and their dependencies) for simple ID formatting, referencing the broader Node/left-pad culture.

Author’s Follow-Up (Design Changes)

  • Authors state the library and format were built quickly after failing to find a clear standard; the blog post was partly marketing.
  • Based on feedback, they:
    • Added an option to generate keys without hyphens.
    • Reiterate that base32 encoding is bijective and does not reduce entropy.
    • Plan to add extra entropy beyond UUIDv7/v4 for API-key use.
    • Plan to add prefixes, inspired in part by GitHub-style tokens.