Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
U

uuidkey

> 编程语言
Open source

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

199 stars0 likes1 views
WebsiteGitHub

About

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

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

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

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:

bash
go get github.com/agentstation/uuidkey

Usage

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

  1. Import the package:
go
import "github.com/agentstation/uuidkey"
  1. Create and parse API Keys:
…
  1. Work with UUID Keys directly:
go
// 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
  1. Decode a Key type to a UUID string with Key format validation:
go
// 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
  1. Decode a Key type to a UUID string with only basic Key length validation:
go
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
  1. Work directly with UUID bytes:
…

CLI Tool

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

Installation

Using Go

bash
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.

…

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) or key (decode)
  • No input generates a new UUID and encodes it

uuidkey apikey

Generate or parse API keys with prefix, entropy, and checksum

  • --prefix: Set the prefix for new API keys (required for generation)
  • --entropy: Set entropy bits (128, 160, or 256; default 160)

uuidkey encode

Explicitly encode a UUID to Base32-Crockford

uuidkey decode

Explicitly decode a Base32-Crockford key to UUID

uuidkey version

Display version and build information

  • --verify: Calculate and display binary checksum
  • --verify-online: Verify checksum against GitHub releases

Global Flags

  • --json, -j: Output in JSON format
  • --quiet, -q: Only output the result value

uuidkey

go
import "github.com/agentstation/uuidkey"

Package uuidkey provides Crockford Base32 encoding that's compatible with the original crock32 number-based approach

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

Index

  • Constants
  • type APIKey
    • func NewAPIKey(prefix, uuid string, opts ...Option) (APIKey, error)
    • func NewAPIKeyFromBytes(prefix string, uuid [16]byte, opts ...Option) (APIKey, error)
    • func ParseAPIKey(apikey string) (APIKey, error)
    • func (a APIKey) String() string
  • type Key
    • func Encode(uuid string, opts ...Option) (Key, error)
    • func EncodeBytes(uuid [16]byte, opts ...Option) (Key, error)
    • func Parse(key string) (Key, error)
    • func (k Key) Bytes() ([16]byte, error)
    • func (k Key) Decode() (string, error)
    • func (k Key) IsValid() bool
    • func (k Key) String() string
    • func (k Key) UUID() (string, error)
  • type Option

Constants

Key validation constraint constants

…

type APIKey

APIKey represents a compound key consisting of four parts or segments: - Prefix: A company or application identifier (e.g., "AGNTSTNP") - Key: A UUID-based identifier encoded in Base32-Crockford - Entropy: Additional segment of random data for increased uniqueness - Checksum: CRC32 checksum of the previous components (8 characters)

Format:

[Prefix]_[UUID Key][Entropy]_[Checksum]

AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8
└─────┘ └──────────────────────────┘└────────────┘ └──────┘
Prefix        Key (crock32 UUID)        Entropy      Checksum
go
type APIKey struct {
    Prefix   string
    Key      Key
    Entropy  string
    Checksum string
}

func NewAPIKey

go
func NewAPIKey(prefix, uuid string, opts ...Option) (APIKey, error)

NewAPIKey creates a new APIKey from a string prefix, string UUID, and options.

func NewAPIKeyFromBytes

go
func NewAPIKeyFromBytes(prefix string, uuid [16]byte, opts ...Option) (APIKey, error)

NewAPIKeyFromBytes creates a new APIKey from a string prefix, [16]byte UUID, and options.

func ParseAPIKey

go
func ParseAPIKey(apikey string) (APIKey, error)

ParseAPIKey will parse a given APIKey string into an APIKey type.

func (APIKey) String

go
func (a APIKey) String() string

String returns the complete API key as a string with all components joined

type Key

Key is a UUID Key string.

go
type Key string

func Encode

go
func Encode(uuid string, opts ...Option) (Key, error)

Encode will encode a given UUID string into a Key. It pre-allocates the exact string capacity needed for better performance.

func EncodeBytes

go
func EncodeBytes(uuid [16]byte, opts ...Option) (Key, error)

EncodeBytes encodes a [16]byte UUID into a Key.

func Parse

go
func Parse(key string) (Key, error)

Parse converts a Key formatted string into a Key type.

func (Key) Bytes

go
func (k Key) Bytes() ([16]byte, error)

Bytes converts a Key to a [16]byte UUID.

func (Key) Decode

go
func (k Key) Decode() (string, error)

Decode will decode a given Key into a UUID string with basic length validation.

func (Key) IsValid

go
func (k Key) IsValid() bool

IsValid verifies if a given Key follows the correct format. The format should be:

  • 31 characters long (with hyphens) or 28 characters (without hyphens)
  • Uppercase
  • Contains only alphanumeric characters
  • Contains 3 hyphens (if hyphenated)
  • Each part is 7 characters long
  • Each part contains only valid crockford base32 characters (I, L, O, U are not allowed)

func (Key) String

go
func (k Key) String() string

String will convert your Key into a string.

func (Key) UUID

go
func (k Key) UUID() (string, error)

UUID will validate and convert a given Key into a UUID string.

type Option

Option is a function that configures options

go
type Option func(c *config)

With128BitEntropy expects 128 bits of entropy in the APIKey

go
var With128BitEntropy Option = func(c *config) {
    c.entropySize = EntropyBits128
}

With160BitEntropy expects 160 bits of entropy in the APIKey

go
var With160BitEntropy Option = func(c *config) {
    c.entropySize = EntropyBits160
}

With256BitEntropy expects 256 bits of entropy in the APIKey

go
var With256BitEntropy Option = func(c *config) {
    c.entropySize = EntropyBits256
}

WithoutHyphens expects no hyphens in the Key

go
var WithoutHyphens Option = func(c *config) {
    c.hyphens = false
}

Generated by gomarkdoc

Makefile

…

Test Coverage

  • Library: 96.2%
  • CLI: 80.1%

All tests now pass reliably. The Cobra state pollution issue has been resolved by using fresh command instances for each test.

Benchmarks

Note: These benchmarks were run on an Apple M2 Max CPU with 12 cores (8 performance and 4 efficiency) and 32 GB of memory, running macOS 14.6.1. The results are not representative of all systems, but should give you a general idea of the performance of the package. I was running other processes on the machine while running the benchmarks.

Your mileage may vary.

…

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Goapiapi-keyapi-keysapikey

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言