Uuidkey

                         _   _  _   _  ___ ____     _  __          
                        | | | || | | ||_ _|  _ \   | |/ /___ _   _ 
                        | | | || | | | | || | | |  | ' // _ \ | | |
                        | |_| || |_| | | || |_| |  | . \  __/ |_| |
                         \___/  \___/ |___|____/   |_|\_\___|\__, |
                                                             |___/ 

<!-- [](https://sourcegraph.com/github.com/agentstation/uuidkey?badge) -->

<!-- [](https://github.com/agentstation/uuidkey/discussions) --> <!-- [](https://twitter.com/agentstationHQ) -->

The uuidkey package encodes UUIDs to a readable Key format via the Base32-Crockford codec.

<div align="center"><h3><a href="https://docs.agentstation.ai/blog/beautiful-api-keys/">📚 Read the original article on why we made this!</a></h3></div>

Note: Thanks to everyone for the feedback and suggestions from the original article, we learned a lot and made improvements to follow the GitHub Secret Scanning format (with checksum) and added additional entropy options to ensure UUIDv7 encoding can be used in a wide variety of use cases. You can still use the Encode function to generate a Key type without the GitHub prefix format and additional entropy - but we recommend using the NewAPIKey function with an 8 character prefix to stay symetrical ;P

Overview

The uuidkey package generates secure, readable API keys by encoding UUIDs using Base32-Crockford with additional security features.

You can use the uuidkey package to generate API keys for your application using the NewAPIKey function (recommended to guarantee at least 128 bits of entropy and follow the GitHub Secret Scanning format) or the Encode function (to generate just a Key type).

Implementation Note: As of v1.1.0, this package uses only the Go standard library's encoding/base32 for Base32-Crockford encoding, removing the external dependency on github.com/richardlehane/crock32. The implementation maintains full backward compatibility while providing constant-time encoding operations.

Language Implementations

The uuidkey package has been implemented in several programming languages:

• Go - This repository (official implementation)

  • Package: github.com/agentstation/uuidkey

• Node.js/TypeScript - By @tanhv90

  • Repository: github.com/tanhv90/uuidkey
  • Package: npm: uuidkey

• .NET/C# - By @fremenkiel

  • Repository: github.com/Fremenkiel/UuidKey

Want to add your implementation? Feel free to open a PR to add it to this list!

API Key Format

AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8
└─────┘ └──────────────────────────┘└────────────┘ └──────┘
Prefix        Key (crock32 UUID)        Entropy      Checksum

Components

1. Prefix - Company/application identifier (e.g., "AGNTSTNP")
2. Key - Base32-Crockford encoded UUID
3. Entropy - Additional random data (128, 160, or 256 bits)
4. Checksum - CRC32 checksum (8 characters) for validation

Security Features

1. Secret Scanning - Formatted for GitHub Secret Scanning detection
2. Validation - CRC32 checksum for error detection and validation
3. Entropy Options - Configurable entropy levels that ensure UUIDv7 security (128, 160, or 256 bits)

Compatibility

Compatible with any UUID library following RFC 4122 specification. Officially tested with:

• github.com/gofrs/uuid (v4.4.0+)
• github.com/google/uuid (v1.6.0+)

Installation

To install the uuidkey package, use the following command:

go get github.com/agentstation/uuidkey

Usage

To use the uuidkey package in your Go code, follow these steps:

1. Import the package:

import "github.com/agentstation/uuidkey"

2. Create and parse API Keys:

// Create a new API Key with default settings (160-bit entropy)
apiKey := uuidkey.NewAPIKey("AGNTSTNP", "d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(apiKey) // Output: AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8

// Create an API Key with 128-bit entropy
apiKey = uuidkey.NewAPIKey("AGNTSTNP", "d1756360-5da0-40df-9926-a76abff5601d", uuidkey.With128BitEntropy)
fmt.Println(apiKey) // Output: AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8

// Parse an existing API Key
apiKey, err := uuidkey.ParseAPIKey("AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8")
if err != nil {
    log.Fatal("Error:", err)
}
fmt.Printf("Prefix: %s, Key: %s, Entropy: %s\n", apiKey.Prefix, apiKey.Key, apiKey.Entropy)

3. Work with UUID Keys directly:

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

// Without hyphens
key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d", uuidkey.WithoutHyphens)
fmt.Println(key) // Output: 38QARV01ET0G6Z2CJD9VA2ZZAR0X

4. Decode a Key type to a UUID string with Key format validation:

// With hyphens
key, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
uuid, err := key.UUID()
if err != nil {
    log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601d

// Without hyphens
key, _ := uuidkey.Parse("38QARV01ET0G6Z2CJD9VA2ZZAR0X")
uuid, err := key.UUID()
if err != nil {
    log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601d

5. Decode a Key type to a UUID string with only basic Key length validation:

key, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
uuid, err := key.Decode()
if err != nil {
    log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601d

6. Work directly with UUID bytes:

// Convert UUID string to bytes
uuidStr := "d1756360-5da0-40df-9926-a76abff5601d"
uuidBytes, err := hex.DecodeString(strings.ReplaceAll(uuidStr, "-", ""))
if err != nil {
    log.Fatal("Error:", err)
}

// Convert to [16]byte array
var uuid [16]byte
copy(uuid[:], uuidBytes)

// Now use the bytes with EncodeBytes (with hyphens)
key, _ := uuidkey.EncodeBytes(uuid)
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X

// Without hyphens
key, _ := uuidkey.EncodeBytes(uuid, uuidkey.WithoutHyphens)
fmt.Println(key) // Output: 38QARV01ET0G6Z2CJD9VA2ZZAR0X

// Convert Key back to UUID bytes
key, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
bytes, err := key.Bytes()
if err != nil {
    log.Fatal("Error:", err)
}
fmt.Printf("%x", bytes) // Output: d17563605da040df9926a76abff5601d

CLI Tool

The uuidkey CLI provides a command-line interface for encoding/decoding UUIDs and generating API keys.

Installation

Using Go

go install github.com/agentstation/uuidkey/cmd/uuidkey@latest

Download Binaries

Pre-built binaries are available on the releases page for:

• Linux (amd64, arm64, arm)
• macOS (amd64, arm64)
• Windows (amd64)
• FreeBSD (amd64, arm64)

CLI Usage

The CLI supports smart command detection - if no input is provided, it generates new values.

# Generate a new UUID v4
uuidkey uuid

# Generate a new UUID v6 (K-sortable)
uuidkey uuid --version 6

# Generate a new UUID v7 (K-sortable with millisecond precision)
uuidkey uuid --version 7

# Encode an existing UUID to Base32-Crockford
uuidkey uuid d1756360-5da0-40df-9926-a76abff5601d

# Generate a new UUID and encode it as a key
uuidkey key

# Encode an existing UUID as a key
uuidkey key d1756360-5da0-40df-9926-a76abff5601d

# Decode a key back to UUID
uuidkey key 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X

# Generate a new API key with default entropy (160 bits)
uuidkey apikey --prefix MYAPP

# Generate an API key with specific entropy
uuidkey apikey --prefix MYAPP --entropy 256

# Parse an existing API key
uuidkey apikey MYAPP_38QARV01ET0G6Z2CJD9VA2ZZAR0X1234567890ABCDEF_A1B2C3D8

# Explicit encode/decode commands
uuidkey encode d1756360-5da0-40df-9926-a76abff5601d
uuidkey decode 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X

# Output as JSON
uuidkey uuid --json

# Quiet mode (only output the result)
uuidkey uuid -q

# Version information
uuidkey version

# Verify binary checksum
uuidkey version --verify

# Verify against GitHub release checksums
uuidkey version --verify-online

Command Reference

uuidkey uuid

Generate or work with UUIDs

• --version, -v: UUID version (4, 6, or 7; default 4)
• --time, -t: Custom timestamp for v6/v7 (RFC3339 format)

uuidkey key

Encode UUIDs to Base32-Crockford keys or decode keys back to UUIDs

• Auto-detects whether input is a UUID (encode)