Making Beautiful API Keys

Original Article ↗ Hacker News Discussion ↗

Efforts to make API keys more “beautiful” — for example by re-encoding UUIDs with Crockford Base32, adding dashes, and tweaking character sets — highlight a tension between developer experience and perceived bikeshedding. Commenters generally favor practical improvements like fixed prefixes, checksums, and easy copy‑paste behavior, while questioning whether visual aesthetics matter for secrets that are almost always pasted rather than typed. The project’s authors respond by adding options such as dashless output, prefixes, and more entropy, positioning the work as lightweight UX polish and content marketing rather than a core security innovation.

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.