Documentation
¶
Overview ¶
Package apikey provides stable API key authentication middleware.
The middleware extracts credentials from Authorization: ApiKey <secret> or X-API-Key, delegates verification to an application-owned Verifier, stores the authenticated principal in request context, and can enforce required scopes. Storage, hashing, rotation, and last-used tracking intentionally belong to the Verifier implementation instead of the core middleware.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/middleware/auth/apikey`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RequireScopeMiddleware ¶
RequireScopeMiddleware requires an authenticated API key principal with scope.
func WithPrincipal ¶
WithPrincipal stores an authenticated API key principal in context.
Example ¶
package main
import (
"context"
"fmt"
"github.com/aatuh/api-toolkit/v4/middleware/auth/apikey"
)
func main() {
ctx := apikey.WithPrincipal(context.Background(), apikey.Principal{
ID: "user-1",
TenantID: "tenant-1",
Scopes: []string{"widgets:read"},
})
principal, ok := apikey.PrincipalFromContext(ctx)
fmt.Println(ok)
fmt.Println(principal.HasScope("widgets:read"))
}
Output: true true
Types ¶
type Middleware ¶
type Middleware struct {
// contains filtered or unexported fields
}
Middleware authenticates requests with API keys.
func NewMiddleware ¶
func NewMiddleware(cfg Config) (*Middleware, error)
NewMiddleware constructs API key middleware.
func (*Middleware) Handler ¶
func (m *Middleware) Handler(next http.Handler) http.Handler
Handler requires a valid API key before calling next.
func (*Middleware) OptionalHandler ¶
func (m *Middleware) OptionalHandler(next http.Handler) http.Handler
OptionalHandler authenticates a valid API key when present and otherwise lets anonymous requests continue. Malformed or invalid credentials still fail.
type PresentedKey ¶
PresentedKey describes a credential extracted from a request.
type Principal ¶
type Principal struct {
ID string
Name string
TenantID string
Scopes []string
Metadata map[string]any
}
Principal describes the authenticated API key owner.
func PrincipalFromContext ¶
PrincipalFromContext returns the authenticated API key principal.
type Verifier ¶
type Verifier interface {
VerifyAPIKey(ctx context.Context, key PresentedKey) (Principal, error)
}
Verifier validates a presented API key and returns its principal.
type VerifierFunc ¶
type VerifierFunc func(ctx context.Context, key PresentedKey) (Principal, error)
VerifierFunc adapts a function to the Verifier interface.
func (VerifierFunc) VerifyAPIKey ¶
func (f VerifierFunc) VerifyAPIKey(ctx context.Context, key PresentedKey) (Principal, error)
VerifyAPIKey validates a presented API key.
Source Files