gofiber/fiber · warning

missing or invalid API Key

Error message

missing or invalid API Key

What it means

Returned by middleware/keyauth when the API key cannot be extracted (the Extractor returns extractors.ErrNotFound), or returned from a custom Config.Validator. It replaces the generic extractor-not-found error with a keyauth-specific message and is delivered via the default ErrorHandler as 401 Unauthorized.

Solutions

1. Send the API key in the channel and scheme the extractor expects (default: Authorization: Bearer <key>).
2. Verify Config.Extractor matches where your client puts the key (header/query/cookie/param).
3. If keys expire, have the client detect 401 and refresh/re-authenticate.
4. Set Config.TokenLookup correctly if you customized it.

Example fix

// before: missing or wrong scheme
// after
req.Header.Set("Authorization", "Bearer "+apiKey)

if errors.Is(err, keyauth.ErrMissingOrMalformedAPIKey) {
    return c.Status(fiber.StatusUnauthorized).SendString("api key required")
}

When it happens

Trigger: A request to a protected route with no API key in the configured source (default Authorization: Bearer), a malformed key, or a Validator that explicitly returns this error (e.g. expired/revoked key).

Common situations: Client forgot the Authorization header; sent the key in the wrong scheme (Basic vs Bearer) or wrong header; a custom extractor pointing at a field the client does not populate; a revoked key whose Validator returns this error.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• csrf: failed to delete token from storage
• csrf: failed to fetch token from storage
• csrf: failed to store token in storage
• csrf: token invalid
• csrf: token not found

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/bf08cfdd964db909. Report an issue: GitHub.

Appendix: source

Thrown at middleware/keyauth/keyauth.go:26

	"github.com/gofiber/fiber/v3"
	"github.com/gofiber/fiber/v3/extractors"
	"github.com/gofiber/fiber/v3/internal/redact"
	"github.com/gofiber/fiber/v3/middleware/logger"
	"github.com/gofiber/utils/v2"
)

// The contextKey type is unexported to prevent collisions with context keys defined in
// other packages.
type contextKey int

// The keys for the values in context
const (
	tokenKey contextKey = iota
)

// ErrMissingOrMalformedAPIKey is returned when the API key is missing or invalid.
var ErrMissingOrMalformedAPIKey = errors.New("missing or invalid API Key")

var registerLogContextTagsOnce sync.Once

// New creates a new middleware handler
func New(config ...Config) fiber.Handler {
	registerLogContextTagsOnce.Do(registerLogContextTags)

	// Init config
	cfg := configDefault(config...)

	// Determine the auth schemes from the extractor chain.
	authSchemes := getAuthSchemes(cfg.Extractor)

	// The challenge value only depends on config, so build it once instead of
	// re-formatting it on every 401/407 response.
	challengeValue := cfg.Challenge
	if len(authSchemes) > 0 {
		challenges := make([]string, 0, len(authSchemes))

View on GitHub (pinned to a105acad6c)