Identity (TypeID)

Every entity in Keysmith has a TypeID. TypeIDs are globally unique, sortable, URL-safe identifiers built on UUIDv7 with a human-readable prefix that tells you what kind of entity you're looking at.

A TypeID looks like this:

akey_01h455vb4pex5vsknk084sn02q

The akey prefix identifies this as an API key. The suffix is a base32-encoded UUIDv7 that encodes creation time, so IDs sort chronologically.

The id package01

The id package wraps the TypeID Go library (v2) with a single ID struct. All entity types share the same struct -- the prefix distinguishes them.

Creating IDs

import "github.com/xraph/keysmith/id"

keyID      := id.New(id.PrefixKey)       // akey_01h455vb...
policyID   := id.New(id.PrefixPolicy)    // kpol_01h455vb...
usageID    := id.New(id.PrefixUsage)     // kusg_01h455vb...
rotationID := id.New(id.PrefixRotation)  // krot_01h455vb...
scopeID    := id.New(id.PrefixScope)     // kscp_01h455vb...

Convenience constructors: id.NewKeyID(), id.NewPolicyID(), id.NewUsageID(), id.NewRotationID(), id.NewScopeID().

Parsing IDs

parsed, err := id.Parse("akey_01h455vb4pex5vsknk084sn02q")
parsed, err := id.ParseWithPrefix("akey_01h455vb...", id.PrefixKey)  // validates prefix
parsed, err := id.ParseKeyID("akey_01h455vb...")                     // convenience

Nil ID

var empty id.ID
empty.IsNil()  // true
empty.String() // ""
id.Nil.IsNil() // true

Database storage

id.ID implements Scanner and driver.Valuer. Stores as a string, returns NULL for nil IDs.

JSON serialization

id.ID implements TextMarshaler and TextUnmarshaler. Nil IDs serialize as empty strings.

Prefix reference02