HTTP Middleware

The middleware package provides Forge-compatible HTTP middleware for API key validation and scope enforcement.

API key authentication

The APIKeyAuth middleware extracts an API key from the Authorization header (Bearer token) or X-API-Key header, validates it, and stores the result in the request context.

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

// Create the middleware
auth := middleware.APIKeyAuth(eng)

// Apply to routes
app.Use(auth)

Key extraction

The middleware looks for the API key in this order:

Authorization: Bearer sk_live_... header
X-API-Key: sk_live_... header

If no key is found, it returns 401 Unauthorized.

Scope enforcement

The RequireScopes middleware checks that the validated key has all the required scopes.

// Require specific scopes
protected := middleware.RequireScopes("read:users", "write:users")

// Chain with auth
app.Use(auth, protected)

If the key does not have the required scopes, it returns 403 Forbidden.

Accessing the validation result

After the middleware validates a key, the validation result is available from the context:

func myHandler(ctx forge.Context) error {
    vr := middleware.ResultFromContext(ctx)
    if vr == nil {
        return fmt.Errorf("no validation result")
    }

    fmt.Println("Key ID:", vr.Key.ID)
    fmt.Println("Tenant:", vr.Key.TenantID)
    fmt.Println("Scopes:", vr.Scopes)
    return nil
}

Full example

import (
    "github.com/xraph/forge"
    "github.com/xraph/keysmith"
    "github.com/xraph/keysmith/middleware"
)

// Public routes — no auth
app.GET("/health", healthHandler)

// Protected routes — require valid API key
app.Group("/api/v1", middleware.APIKeyAuth(eng), func(g *forge.Group) {
    // Requires read:users scope
    g.GET("/users", middleware.RequireScopes("read:users"), listUsersHandler)

    // Requires write:users scope
    g.POST("/users", middleware.RequireScopes("write:users"), createUserHandler)
})