Composable API key management for Go

Forge your keys

API key generation, validation, rotation, revocation, scoped permissions, usage analytics, and policy enforcement — tenant-scoped, plugin-extensible, and composable.

$go get github.com/xraph/keysmith

Get Started GitHub

Create

Hash

Store

Request

Validate

Authorize

key.created

hashed

key.validated

active

usage.record

tracked

SHA-256

Multi-Tenant

TypeID

Pluggable

Features

Everything you need for API key management

Keysmith handles the hard parts — key generation, hash storage, tenant isolation, policy enforcement, and usage analytics — so you can focus on your application.

API Key Lifecycle

Create, validate, rotate, revoke, suspend, and reactivate API keys. Raw keys are returned once at creation; only SHA-256 hashes are stored.

create.go

result, _ := eng.CreateKey(ctx,
  &keysmith.CreateKeyInput{
    Name:   "Production Key",
    Prefix: "sk",
    Environment: key.EnvLive,
    Scopes: []string{"read:users"},
  })
 
fmt.Println(result.RawKey)
"text-fd-muted-foreground/60 italic">// sk_live_a3f8b2c9e1d4...

Scoped Permissions

Assign hierarchical permission scopes to keys. Validate that a key has the required scopes before granting access to protected resources.

scopes.go

"text-fd-muted-foreground/60 italic">// Assign scopes to a key
eng.AssignScopes(ctx, keyID,
  []string{"read:users", "write:users"})
 
"text-fd-muted-foreground/60 italic">// Validate key and check scopes
vr, _ := eng.ValidateKey(ctx, rawKey)
fmt.Println(vr.Scopes)
"text-fd-muted-foreground/60 italic">// [read:users write:users]

Policy Engine

Rate limits, IP allowlists, origin restrictions, key lifetime constraints, and usage quotas. Attach policies to keys for fine-grained control.

policies.go

eng.CreatePolicy(ctx, &policy.Policy{
  Name:         "Standard",
  RateLimit:    1000,
  RateWindow:   time.Minute,
  AllowedIPs:   []string{"10.0.0.0/8"},
  MaxKeyAge:    90 * 24 * time.Hour,
})

Key Rotation

Zero-downtime key rotation with configurable grace periods. Old keys remain valid during the grace window while clients migrate to the new key.

rotation.go

newResult, _ := eng.RotateKey(ctx,
  keyID,
  rotation.ReasonScheduled,
  24*time.Hour, "text-fd-muted-foreground/60 italic">// grace period
)
 
"text-fd-muted-foreground/60 italic">// Old key still valid for 24 hours
"text-fd-muted-foreground/60 italic">// New key: newResult.RawKey

Multi-Tenant Isolation

Every operation is scoped to app and tenant via context. Cross-tenant access is structurally impossible at the store layer.

scope.go

ctx = keysmith.WithTenant(ctx,
  "my-app", "tenant-1")
 
"text-fd-muted-foreground/60 italic">// All key operations are automatically
"text-fd-muted-foreground/60 italic">// scoped to this app + tenant.
"text-fd-muted-foreground/60 italic">// Keys, policies, scopes, and usage
"text-fd-muted-foreground/60 italic">// are fully isolated per tenant.

Plugin System

Opt-in lifecycle hooks for audit trails, metrics, and authorization sync. Register plugins that fire on key creation, validation, rotation, and more.

plugins.go

eng, _ := keysmith.NewEngine(
  keysmith.WithStore(store),
  keysmith.WithExtension(
    audithook.New(myRecorder)),
  keysmith.WithExtension(
    observability.NewMetricsExtension()),
)

Key Lifecycle Pipeline

From creation to validation.

Keysmith orchestrates the entire API key lifecycle — hashing, tenant scoping, policy enforcement, scope checking, and usage recording.

SHA-256 Hash Storage

Raw API keys are never stored. Only SHA-256 hashes are persisted, and raw keys are returned exactly once at creation time. Constant-time comparison prevents timing attacks.

Zero-Downtime Rotation

Rotate keys with configurable grace periods. Both old and new keys validate during the grace window, giving clients time to migrate without service interruption.

Lifecycle Hook Plugins

Every key event fires lifecycle hooks to registered plugins. Built-in plugins provide audit trails, metrics counters, and Warden authorization sync.

Learn about the architecture

Request

key.create

HashSHA-256

Validatepolicy

scope.applied

✓ Scoped

key.validated

↻ Checking

usage.recorded

✓ Tracked

Valid

Validating

Rate Limited

Revoked

Developer Experience

Simple API. Powerful primitives.

Create and validate API keys in under 20 lines. Keysmith handles hashing, scoping, and lifecycle management.

Create Key

main.go

1package main
2 
3import (
4  "context"
5  "fmt"
6  "log"
7 
8  "github.com/xraph/keysmith"
9  "github.com/xraph/keysmith/key"
10  "github.com/xraph/keysmith/store/memory"
11)
12 
13func main() {
14  ctx := context.Background()
15  eng, _ := keysmith.NewEngine(
16    keysmith.WithStore(memory.New()),
17  )
18 
19  ctx = keysmith.WithTenant(ctx,
20    "my-app", "tenant-1")
21 
22  "text-fd-muted-foreground/60 italic">// Create an API key — raw key shown once
23  result, _ := eng.CreateKey(ctx,
24    &keysmith.CreateKeyInput{
25      Name:   "Production Key",
26      Prefix: "sk",
27      Environment: key.EnvLive,
28      Scopes: []string{"read:users"},
29    })
30 
31  fmt.Println("Key:", result.RawKey)
32  "text-fd-muted-foreground/60 italic">// sk_live_a3f8b2c9e1d4...
33}

Validate Key

validate.go

1package main
2 
3import (
4  "context"
5  "fmt"
6  "log"
7 
8  "github.com/xraph/keysmith"
9  "github.com/xraph/keysmith/store/memory"
10)
11 
12func main() {
13  ctx := context.Background()
14  eng, _ := keysmith.NewEngine(
15    keysmith.WithStore(memory.New()),
16  )
17 
18  ctx = keysmith.WithTenant(ctx,
19    "my-app", "tenant-1")
20 
21  "text-fd-muted-foreground/60 italic">// Validate an incoming API key
22  vr, err := eng.ValidateKey(ctx, rawKey)
23  if err != nil {
24    log.Fatal("invalid key:", err)
25  }
26 
27  fmt.Println("Tenant:", vr.Key.TenantID)
28  fmt.Println("Scopes:", vr.Scopes)
29  fmt.Println("State:", vr.Key.State)
30  "text-fd-muted-foreground/60 italic">// Tenant: tenant-1
31  "text-fd-muted-foreground/60 italic">// Scopes: [read:users]
32  "text-fd-muted-foreground/60 italic">// State: active
33}

Start building with Keysmith

Add API key management to your Go service in minutes. Keysmith handles key generation, hash storage, tenant isolation, policy enforcement, and usage analytics out of the box.

$go get github.com/xraph/keysmith

Get Started View Examples