Documentation
Guides

Token management

TokenStore adds server-side named bearer tokens with revocation. When configured, every request validates the token against the database — a revoked or expired token is rejected immediately, even if the HMAC signature is valid.

Wiring

main.go
app := forge.New(forge.MustConfig(forge.Config{
    BaseURL:    "https://mysite.com",
    Secret:     []byte(os.Getenv("SECRET")),
    DB:         db,
    TokenStore: forge.NewTokenStore(db, os.Getenv("SECRET")),
}))

Create the forge_tokens table once before starting:

migration.sql
CREATE TABLE forge_tokens (
    id         TEXT PRIMARY KEY,
    name       TEXT NOT NULL,
    role       TEXT NOT NULL,
    token_hash TEXT NOT NULL,
    expires_at TEXT NOT NULL,
    revoked_at TEXT,
    created_at TEXT NOT NULL
);

Bootstrap

On first startup with an empty forge_tokens table, Forge auto-creates a bootstrap admin token and emits it via slog.Warn:

startup log
WARN forge: bootstrap admin token created token=<plaintext>

Copy this token immediately. Use it with forge-cli init or the create_token MCP tool to issue long-lived named tokens, then discard it.

A token produced by forge.SignToken in main() is rejected when TokenStore is configured — VerifyBearerToken only accepts tokens that exist in the store. Use TokenStore.Create or forge-cli instead.

Go API

main.go
// Issue a named token — returns plaintext once, never retrievable again
token, err := app.TokenStore().Create(ctx, "alice-author", "author", 365*24*time.Hour)

// List all tokens
records, err := app.TokenStore().List(ctx)

// Revoke by ID
err := app.TokenStore().Revoke(ctx, id)

Create returns the plaintext token once. It cannot be retrieved again.

ErrLastAdmin (HTTP 409) is returned if you attempt to revoke the last active admin token. Create a replacement first.

MCP tools

All token operations via MCP require Admin role.

ToolDescription
create_tokenIssue a new named token with a given role and TTL. Returns the plaintext token once.
list_tokensList all tokens with name, role, expiry, and revoked status.
revoke_tokenRevoke a token by ID — effective immediately.

CLI

terminal
forge-cli token create <name> <role> <ttl-days>
forge-cli token list
forge-cli token revoke <id>

See forge-cli for full flag details and configuration.