Key Auth - 💧 Mizu

Overview

The keyauth middleware provides API key authentication. It validates API keys from headers, query parameters, or cookies. Perfect for machine-to-machine authentication and public APIs. Use it when you need:

API key authentication
Service-to-service authentication
Third-party API access control
Simple API protection without user sessions

Installation

import "github.com/go-mizu/mizu/middlewares/keyauth"

Quick Start

app := mizu.New()

// Validate against a list of valid keys
app.Use(keyauth.New(keyauth.ValidateKeys(
    "key-abc123",
    "key-def456",
)))

Configuration

Options

Option	Type	Default	Description
`Validator`	`KeyValidator`	-	Function to validate API keys
`KeyLookup`	`string`	`"header:X-API-Key"`	Where to find the key
`AuthScheme`	`string`	`""`	Scheme prefix for header lookup
`ErrorHandler`	`func(*mizu.Ctx, error) error`	-	Custom error handler

KeyLookup Format

The KeyLookup option uses the format "source:name":

Source	Example	Description
`header`	`"header:X-API-Key"`	Read from header
`query`	`"query:api_key"`	Read from query parameter
`cookie`	`"cookie:api_key"`	Read from cookie

Examples

Static API Keys

validKeys := keyauth.ValidateKeys(
    "production-key-abc",
    "production-key-xyz",
)

app.Use(keyauth.New(validKeys))

Database Lookup

app.Use(keyauth.New(func(key string) (bool, error) {
    // Look up key in database
    apiKey, err := db.GetAPIKey(key)
    if err != nil {
        if err == sql.ErrNoRows {
            return false, nil // Key not found
        }
        return false, err // Database error
    }

    // Check if key is active and not expired
    if !apiKey.Active || apiKey.ExpiresAt.Before(time.Now()) {
        return false, nil
    }

    return true, nil
}))

Query Parameter

// Accept key via ?api_key=xxx
app.Use(keyauth.WithOptions(keyauth.Options{
    KeyLookup: "query:api_key",
    Validator: func(key string) (bool, error) {
        return key == "valid-key", nil
    },
}))

Multiple Lookup Sources

// Try header first, then query parameter
app.Use(keyauth.WithOptions(keyauth.Options{
    KeyLookup: "header:X-API-Key",
    Validator: func(key string) (bool, error) {
        return validateKey(key)
    },
}))

// Add fallback for query
app.Use(keyauth.WithOptions(keyauth.Options{
    KeyLookup: "query:api_key",
    Validator: func(key string) (bool, error) {
        return validateKey(key)
    },
}))

With Auth Scheme

// Expect "ApiKey xxx" in Authorization header
app.Use(keyauth.WithOptions(keyauth.Options{
    KeyLookup:  "header:Authorization",
    AuthScheme: "ApiKey",
    Validator:  validateKey,
}))

Custom Error Handler

app.Use(keyauth.WithOptions(keyauth.Options{
    Validator: validateKey,
    ErrorHandler: func(c *mizu.Ctx, err error) error {
        if err == keyauth.ErrKeyMissing {
            return c.JSON(401, map[string]string{
                "error":   "API key required",
                "hint":    "Include X-API-Key header",
            })
        }
        return c.JSON(403, map[string]string{
            "error": "Invalid API key",
        })
    },
}))

Access API Key in Handler

func handler(c *mizu.Ctx) error {
    // Get the validated API key
    key := keyauth.Get(c)

    // Log for audit
    c.Logger().Info("API request", "key", key[:8]+"...")

    return c.JSON(200, data)
}

Rate Limiting Per Key

// Custom rate limiter based on API key
func rateLimit() mizu.Middleware {
    return func(next mizu.Handler) mizu.Handler {
        return func(c *mizu.Ctx) error {
            key := keyauth.Get(c)
            if !rateLimiter.Allow(key) {
                return c.Text(429, "Rate limit exceeded")
            }
            return next(c)
        }
    }
}

app.Use(keyauth.New(validateKey))
app.Use(rateLimit())

API Reference

Functions

// New creates middleware with validator
func New(validator KeyValidator) mizu.Middleware

// WithOptions creates middleware with full configuration
func WithOptions(opts Options) mizu.Middleware

// ValidateKeys creates validator for static key list
func ValidateKeys(keys ...string) KeyValidator

Extracting Key

// FromContext extracts API key from context
func FromContext(c *mizu.Ctx) string

// Get is an alias for FromContext
func Get(c *mizu.Ctx) string

Types

// KeyValidator validates an API key
type KeyValidator func(key string) (valid bool, err error)

Error Types

var (
    ErrKeyMissing // API key not found in request
    ErrKeyInvalid // API key validation failed
)

Technical Details

Implementation Overview

The keyauth middleware implements a flexible API key authentication system with support for multiple key sources (headers, query parameters, and cookies) and customizable validation logic. Key Components:

Key Extraction: The middleware parses the KeyLookup option to determine where to extract the API key from:
- Header extraction with optional auth scheme prefix support
- Query parameter extraction
- Cookie extraction
Validation Pipeline:
- Extract key from the configured source
- Return 401 Unauthorized if key is missing
- Execute custom validator function
- Return 403 Forbidden if validation fails or returns error
- Store validated key in request context for downstream handlers
Context Storage: Validated keys are stored using a private contextKey type, ensuring type-safe retrieval and preventing context key collisions.
Error Handling: The middleware provides two error handling paths:
- Custom error handler (if configured)
- Default handler: 401 for missing keys, 403 for invalid keys or validation errors

Key Extraction Logic

KeyLookup Format: "source:name"

Header Source:
  - Reads from request.Header.Get(name)
  - If AuthScheme is set, strips the scheme prefix
  - Example: "header:Authorization" with AuthScheme="ApiKey"
    "ApiKey abc123" -> "abc123"

Query Source:
  - Reads from URL query parameter
  - Example: "query:api_key" -> ?api_key=value

Cookie Source:
  - Reads from HTTP cookie
  - Example: "cookie:auth_token"

Validator Function

The KeyValidator function signature:

type KeyValidator func(key string) (valid bool, err error)

Return Values:

(true, nil) - Key is valid, allow request
(false, nil) - Key is invalid, return 403 Forbidden
(_, error) - Validation error occurred, return 403 with error

Static Key Validation

The ValidateKeys helper creates a validator using a map for O(1) lookup:

func ValidateKeys(keys ...string) KeyValidator {
    keySet := make(map[string]bool)
    for _, k := range keys {
        keySet[k] = true
    }
    return func(key string) (bool, error) {
        return keySet[key], nil
    }
}

Security Considerations

Key Generation - Use cryptographically secure random keys
Key Storage - Hash keys in database, never store plain text
Key Rotation - Support key rotation without downtime
Scoping - Consider scoped keys with limited permissions
Logging - Log key usage but not full keys

Secure Key Generation

import "crypto/rand"

func generateAPIKey() string {
    b := make([]byte, 32)
    rand.Read(b)
    return "sk_" + hex.EncodeToString(b)
}

Best Practices

Use different keys for different environments
Implement key expiration
Add rate limiting per key
Log API key usage for auditing
Support multiple keys per user/service
Provide key management API

Testing

The keyauth middleware includes comprehensive test coverage for all functionality:

Test Case	Description	Expected Behavior
TestNew - valid key	Valid API key provided in X-API-Key header	Returns 200 OK, allows request through
TestNew - invalid key	Invalid API key provided	Returns 403 Forbidden, blocks request
TestNew - missing key	No API key provided	Returns 401 Unauthorized, blocks request
TestWithOptions_QueryLookup	API key provided via query parameter	Returns 200 OK when key is valid
TestWithOptions_CookieLookup	API key provided via cookie	Returns 200 OK when key is valid
TestWithOptions_AuthScheme	API key with “ApiKey” scheme in Authorization header	Strips scheme prefix, validates key, returns 200 OK
TestWithOptions_ErrorHandler	Custom error handler configured	Custom error handler is invoked, returns custom JSON response
TestWithOptions_ValidatorError	Validator returns error (e.g., database error)	Returns 403 Forbidden with error message
TestFromContext	Retrieve API key from context after validation	Returns the validated API key string
TestGet	Test Get() function as alias for FromContext()	Both functions return the same key value
TestValidateKeys - key1	Static validator with “key1” in allowed list	Returns valid=true
TestValidateKeys - key2	Static validator with “key2” in allowed list	Returns valid=true
TestValidateKeys - key3	Static validator with “key3” in allowed list	Returns valid=true
TestValidateKeys - key4	Static validator with “key4” not in allowed list	Returns valid=false
TestValidateKeys - empty	Static validator with empty string	Returns valid=false
TestWithOptions_Panics - no validator	Create middleware without validator	Panics with error message
TestWithOptions_Panics - invalid lookup	Create middleware with invalid KeyLookup format	Panics with error message
TestErrors	Verify error constants	ErrKeyMissing and ErrKeyInvalid return correct messages

Running Tests

# Run all keyauth tests
go test ./middlewares/keyauth

# Run with coverage
go test -cover ./middlewares/keyauth

# Run specific test
go test -run TestNew ./middlewares/keyauth

basicauth - Username/password authentication
bearerauth - Bearer token authentication
ratelimit - Rate limiting

​Overview

​Installation

​Quick Start

​Configuration

​Options

​KeyLookup Format

​Examples

​Static API Keys

​Database Lookup

​Query Parameter

​Multiple Lookup Sources

​With Auth Scheme

​Custom Error Handler

​Access API Key in Handler

​Rate Limiting Per Key

​API Reference

​Functions

​Extracting Key

​Types

​Error Types

​Technical Details

​Implementation Overview

​Key Extraction Logic

​Validator Function

​Static Key Validation

​Security Considerations

​Secure Key Generation

​Best Practices

​Testing

​Running Tests

​Related Middlewares