Apache APISIX Key Auth Rejects Valid Keys

You encounter a apisix configuration issue that prevents your workflow from completing. This guide walks through the fix step by step.

Wrong ❌

# Route with key-auth enabled but consumer with key does not exist
{
  "plugins": { "key-auth": {} },
  "uri": "/api/*"
}
# No consumer with key-auth credential exists

Wrong Output

All requests return 401 Unauthorized. No valid consumer with matching API key.

Right ✅

# Create consumer with key-auth credential
PUT /apisix/admin/consumers
{
  "username": "my-user",
  "plugins": {
    "key-auth": {
      "key": "my-secret-api-key"
    }
  }
}
# Route with key-auth plugin
PUT /apisix/admin/routes/1
{
  "methods": ["GET"],
  "uri": "/api/*",
  "plugins": { "key-auth": {} },
  "upstream": { "type": "roundrobin", "nodes": { "backend:3000": 1 } }
}

Right Output

Authenticated requests succeed. Invalid key returns 401. API key validated against consumer.

Prevention

• Create consumers with key-auth credentials before enabling the plugin on routes.
• Use strong random API keys: openssl rand -hex 32.
• Store keys securely - they are hashed by APISIX.
• Use different keys for different consumers.
• Test with both valid and invalid API keys.

DodaTech applies similar defensive patterns across Doda Browser, DodaZIP, and Durga Antivirus Pro infrastructure for production reliability.

Common Mistakes with key auth

1. Forgetting deriving (Show, Eq) on custom data types needed for debugging
2. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
3. Using head and tail instead of pattern matching, causing runtime errors on empty lists

These mistakes appear frequently in real-world APISIX code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

This quick fix is part of the DodaTech infrastructure engineering series. Learn more at DodaTech tutorials.