Summary: In order to improve the developer experience, AgentStation created the uuidkey package to encode UUIDs into beautiful and easy-to-read API keys. This package supports UUIDv7 and can decode keys for database sorting and indexing.

Question:

API keys are an important part of a user’s first interaction with AgentStation products. We want keys to be beautiful and easy to use, but there seems to be a lack of standards in the industry. As a developer-focused startup, we invest time and effort into finding the ideal solution.

Most API keys suck:

We have the following requirements for API keys:

• Safety
• Globally unique
• Sortable
• Excellent performance in Postgres
• Beautiful appearance

However, most API keys lack aesthetics and are often inconsistently formatted random characters that are difficult to read, sort, and identify. We want API keys to be aesthetically pleasing and symmetrical like the good things in life.

IDs we rejected:

Too random, easy to guess, ugly in appearance...all unsatisfactory.

• Integers and BigInt: Simple to read and easy to sort. But they expose the number of keys, are easy to guess, and provide insufficient security.
• NanoIDs: Provides completely random, customizable IDs, ideal for public-facing identifiers. But lacks timestamp information for sorting and debugging.
• UUIDs: industry standard, with two versions worth considering:
  • UUIDv4: Purely random characters, simple and effective.
  • UUIDv7: Includes timestamp for easy debugging and database query sorting.
• ULIDs: contain timestamps and are encoded using Base32 for better readability. But we prefer UUID native Postgres support, and its aesthetics are still insufficient.

Our solution:

Due to the lack of aesthetics (symmetry) of existing solutions, we created our own approach:

1. Use UUIDv7 as base ID, utilizing timestamp information.
2. Use Crockford Base32 encoding to improve readability.
3. Add beautiful dashes to enhance the visual effect.

Result:

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

Our key:

• 31 characters (28 without dashes), shorter than the 36 characters of a UUID.
• Highly readable paragraph containing 4 sets of 7 uppercase letters and numbers, with a "blocky" aesthetic and readability.
• Can be sorted chronologically when stored as decoded UUID.
• The timestamp in the user-visible key is obfuscated (but can still be decoded by tech-savvy users). We think the timestamp metadata in the key is an added bonus, and you can also choose to use UUIDv4!

Why choose UUIDv7?

In addition to the advantages of timestamps, UUIDv7 will receive native support in Postgres v18. While it's currently possible to generate UUIDv7 server-side using extensions, native Postgres support would definitely perform better and work well with uuidkey.Encode().

In our implementation we currently generate keys at the application layer and store them as UUIDs for sorting and indexing. Once Postgres v18 is released, we will switch to Postgres builds to reduce load on the application layer and achieve better performance.

Why choose Crockford Base32?

We chose Crockford Base32 encoding because it:

• Use only uppercase letters and numbers to improve readability.
• Reduce key length by about 1/5.
• Mapping is efficient and predictable.

Why use dash?

Dash keys are "blocky" and symmetrical. If you gray out the individual characters, they look almost like a barcode. We think this makes it easy to quickly read part of a key to identify it.

The dash does remove the convenient double-click copy functionality, but we think this is a worthwhile trade-off for readability. We don't want users copying and pasting them everywhere, in fact we want them to be handled with care. Ideally, users would only copy a key once when generating it in our dashboard - so we added a copy button to the UI to solve this problem.

uuidkey package:

We open sourced these design choices at github.com/agentstation/uuidkey. If you agree with our aesthetics, reasoning, and symmetry, and would like to have your own beautiful API key, feel free to try our open source project.

uuidkey The core of the package is to encode a UUID into a readable key format via the Base32-Crockford codec and decode it back to a UUID.

Encoding:

The code snippet has been given in the original text and will not be repeated here.

Decoding:

The code snippet has been given in the original text and will not be repeated here.

The package is designed to work with any UUID that follows the official UUID specification (RFC 4122), but we specifically test and maintain compatibility with the two most popular UUID Go generators:

• Gofrs
• Google

Installation is easy:

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

Basic usage:

<code>go get github.com/agentstation/uuidkey</code>

We strive to keep overhead to a minimum:

Performance benchmark test data has been given in the original text and will not be repeated here.

Contribute to uuidkey:

We are committed to maintaining uuidkey as a reliable open source tool because we use it in production - contributions welcome!

If you find it useful or have suggestions for improvements, we'd love to hear from you in our GitHub issues or Discord community.

Prior technology and the shoulders of giants:

After we released the project, we found a few projects with similar implementations, but still did not meet our criteria for encoding and decoding UUIDs using Go.

• uuidapikey - Go, but does not support encoding or decoding UUID input.
• based_uuid - Ruby, but for public IDs.

Summary:

At AgentStation, we are building a platform that allows AI agents to have their own virtual workstation to run browsers, attend meetings, and execute code. As we scale to thousands of workstations, having sortable, high-performance keys is a practical infrastructure.

But we also believe that developers appreciate the beauty of symmetry as much as we do, even in API keys.

We hope you find uuidkey both practical and beautiful.

The footnotes have been given in the original text and will not be repeated here.

The above is the detailed content of Making Beautiful API Keys. For more information, please follow other related articles on the PHP Chinese website!