Help us shape the future of Go! Take the 2026 Go Developer Survey

apikey

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 28 Imported by: 0

README

apikey

Long-lived keys for machine-to-machine calls, scoped to a user and revocable one at a time.

Keys are hashed with SHA-256 before storage, so a database dump does not hand anyone working credentials. A short visible prefix is kept in the clear purely so lookup can find the right row without scanning every hash. The auth strategy checks both the Authorization header and X-API-Key, so callers can use whichever their HTTP client makes easy.

The plaintext key is returned exactly once, at creation.

Use it when

  • A service, a CI job or a CLI needs to call your API without a browser
  • You want per-integration credentials that can be revoked without touching anyone's password
  • You're building a public API and users need to generate their own keys

Skip it when

  • The caller is a browser with a logged-in human. Sessions are the right shape for that
  • You need short-lived, scoped, audience-bound tokens. That's oauth2provider with the client credentials grant
  • You have no way to rotate keys. A key that never expires is a credential you cannot take back once it leaks

Wiring

authsome.WithPlugin(apikey.New(apikey.Config{
    MaxKeysPerUser: 10,
    DefaultExpiry:  90 * 24 * time.Hour,
}))

Set DefaultExpiry. Keys that never expire are the ones still working three years after the person who made them left.

Config

Field Type Default What it does
PathPrefix string /v1/keys Where the management routes are mounted
MaxKeysPerUser int 0 Cap on active keys per user. 0 is unlimited
DefaultExpiry time.Duration 0 Default TTL for a new key. Zero means it never expires

Settings

Key Default
apikey.max_keys_per_user 0
apikey.default_expiry_seconds 0

Endpoints

Registered under PathPrefix, /v1/keys by default.

Method Path Purpose
POST `` Create a key. The plaintext is in this response and nowhere else
GET `` List the caller's keys, metadata only
DELETE /:keyId Revoke a key

Lifecycle hooks

None. It registers a StrategyProvider that authenticates requests carrying a key.

oauth2provider if you need real OAuth2 client credentials with scopes and expiry rather than a static secret.

Documentation

Overview

contract.go: Wires the apikey plugin into the forge-dashboard contract surface via plugin.ContractContributor.

Package apikey provides an API key authentication plugin for AuthSome.

The apikey plugin enables machine-to-machine authentication. API keys are created per-user, hashed with SHA-256, and identified by a visible prefix during lookup. The plugin registers HTTP routes for key lifecycle management and an authentication strategy that checks the Authorization or X-API-Key headers.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// SettingMaxKeysPerUser controls the maximum number of active API keys per user.
	SettingMaxKeysPerUser = settings.Define("apikey.max_keys_per_user", 0,
		settings.WithDisplayName("Max Keys Per User"),
		settings.WithDescription("Maximum number of active API keys per user (0 = unlimited)"),
		settings.WithCategory("API Keys"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithEnforceable(),
		settings.WithInputType(formconfig.FieldNumber),
		settings.WithUIValidation(formconfig.Validation{Min: intPtr(0), Max: intPtr(100)}),
		settings.WithHelpText("Set to 0 for unlimited keys. Default: 0"),
		settings.WithOrder(10),
	)

	// SettingDefaultExpirySeconds controls the default TTL for newly created keys.
	SettingDefaultExpirySeconds = settings.Define("apikey.default_expiry_seconds", 0,
		settings.WithDisplayName("Default Key Expiry (seconds)"),
		settings.WithDescription("Default TTL for newly created API keys in seconds (0 = no expiry)"),
		settings.WithCategory("API Keys"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithInputType(formconfig.FieldNumber),
		settings.WithUIValidation(formconfig.Validation{Min: intPtr(0)}),
		settings.WithHelpText("Set to 0 for keys that never expire. Default: 0"),
		settings.WithOrder(20),
	)
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	// PathPrefix is the HTTP path prefix for API key routes.
	// Defaults to "/v1/keys".
	PathPrefix string

	// MaxKeysPerUser limits the number of active API keys per user.
	// 0 means unlimited.
	MaxKeysPerUser int

	// DefaultExpiry sets the default TTL for newly created keys.
	// Zero means keys never expire.
	DefaultExpiry time.Duration
}

Config configures the API key plugin.

type CreateKeyRequest added in v1.9.0 

type CreateKeyRequest struct {
	AppID string `json:"app_id"`
	// UserID names the key's owner. Optional — defaults to the authenticated
	// caller. Naming another user requires the manage/apikey permission.
	UserID string   `json:"user_id,omitempty"`
	Name   string   `json:"name"`
	Scopes []string `json:"scopes,omitempty"`
}

CreateKeyRequest is the request body for creating an API key.

type CreateKeyResponse added in v1.9.0 

type CreateKeyResponse struct {
	ID              string   `json:"id"`
	Key             string   `json:"key"`
	KeyPrefix       string   `json:"key_prefix"`
	PublicKey       string   `json:"public_key"`
	PublicKeyPrefix string   `json:"public_key_prefix"`
	Name            string   `json:"name"`
	Scopes          []string `json:"scopes,omitempty"`
	ExpiresAt       *string  `json:"expires_at,omitempty"`
	CreatedAt       string   `json:"created_at"`
}

CreateKeyResponse is returned when a key is created.

type KeyListItem added in v1.9.0 

type KeyListItem struct {
	ID              string   `json:"id"`
	Name            string   `json:"name"`
	KeyPrefix       string   `json:"key_prefix"`
	PublicKeyPrefix string   `json:"public_key_prefix,omitempty"`
	Scopes          []string `json:"scopes,omitempty"`
	ExpiresAt       *string  `json:"expires_at,omitempty"`
	LastUsedAt      *string  `json:"last_used_at,omitempty"`
	Revoked         bool     `json:"revoked"`
	CreatedAt       string   `json:"created_at"`
}

KeyListItem represents an API key in list responses (no raw key).

type ListKeysRequest added in v1.9.0 

type ListKeysRequest struct {
	AppID  string `query:"app_id"`
	UserID string `query:"user_id,omitempty"`
}

ListKeysRequest contains query parameters for listing API keys.

type ListKeysResponse added in v1.9.0 

type ListKeysResponse struct {
	Keys  []KeyListItem `json:"keys"`
	Total int           `json:"total"`
}

ListKeysResponse is the response for listing API keys.

type Plugin 

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin is the API key authentication plugin.

func New added in v1.9.0 

func New(cfg ...Config) *Plugin

New creates a new API key plugin with the given configuration. The API key store is resolved automatically from the engine during OnInit.

func (*Plugin) DeclareSettings added in v1.9.0 

func (p *Plugin) DeclareSettings(m *settings.Manager) error

DeclareSettings implements plugin.SettingsProvider.

func (*Plugin) Name added in v1.9.0 

func (p *Plugin) Name() string

Name returns the plugin name.

func (*Plugin) OnInit added in v1.9.0 

func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error

OnInit captures bridge references from the engine.

func (*Plugin) RegisterContract added in v1.9.0 

func (p *Plugin) RegisterContract(
	d *dispatcher.Dispatcher,
	reg contract.Registry,
	wreg contract.WardenRegistry,
	engine plugin.Engine,
) error

func (*Plugin) RegisterRoutes 

func (p *Plugin) RegisterRoutes(router forge.Router) error

RegisterRoutes registers API key management routes on a forge.Router.

func (*Plugin) SetStore added in v1.9.0 

func (p *Plugin) SetStore(s apikey.Store)

SetStore allows direct API key store injection for testing.

func (*Plugin) Strategy added in v1.9.0 

func (p *Plugin) Strategy() strategy.Strategy

Strategy returns the API key authentication strategy.

func (*Plugin) StrategyPriority added in v1.9.0 

func (p *Plugin) StrategyPriority() int

StrategyPriority returns the evaluation priority for the API key strategy. API key auth is evaluated after session-based auth (priority 100).

type PrincipalAuthGate added in v1.9.0 

type PrincipalAuthGate interface {
	Authorize(ctx context.Context, a *principal.AuthAttempt) error
	Observe(ctx context.Context, a *principal.AuthAttempt, s *session.Session)
}

PrincipalAuthGate scores a machine caller and may deny it. The apikey plugin holds this rather than the engine so it does not import authsome.

Authorize runs the BeforePrincipalAuth chain; a returned error must abort the request. Observe runs after a session has been minted and never blocks authentication: errors from it are logged, not propagated.

type PrincipalResolver added in v1.9.0 

type PrincipalResolver func(ctx context.Context, ref principal.Ref) (*principal.Principal, error)

PrincipalResolver resolves any caller, human or otherwise, by ref. Taken as a function rather than the whole engine so the strategy keeps its narrow dependency surface, matching UserResolver above.

type RevokeKeyRequest added in v1.9.0 

type RevokeKeyRequest struct {
	KeyID string `path:"keyId"`
}

RevokeKeyRequest contains the path parameter for revoking an API key.

type UserResolver added in v1.9.0 

type UserResolver func(ctx context.Context, userID string) (*user.User, error)

UserResolver resolves a user by ID string.

Source Files

View all Source files

Directories

Path Synopsis
Package contract wires the apikey plugin's intent surface into the forge-dashboard contract registry.
 Package contract wires the apikey plugin's intent surface into the forge-dashboard contract registry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.