What causes "unsupported apiKey location %s" in crowdsecurity/crowdsec?

Fix the security scheme in the OpenAPI schema so apiKey 'in' is exactly one of: query, header, cookie.

unsupported apiKey location %s

Error message

unsupported apiKey location %s

What it means

The AppSec request validator only enforces apiKey security schemes located in 'query', 'header', or 'cookie'. If the OpenAPI schema declares an apiKey scheme with any other 'in' value, the per-request authentication check in authFunc returns this error, meaning the validator cannot locate the API key and fails the request validation.

Source

Thrown at pkg/appsec/api_validation/api_validation.go:280

				values := input.RequestValidationInput.Request.Header[canonicalHeaderName]
				if len(values) == 0 {
					return fmt.Errorf("header %s not found", input.SecurityScheme.Name)
				}
				if len(values) > 1 {
					return fmt.Errorf("multiple headers with name %s found", input.SecurityScheme.Name)
				}
				authTokenValue = values[0]
			case "cookie":
				cookieValues := input.RequestValidationInput.Request.CookiesNamed(input.SecurityScheme.Name)
				if len(cookieValues) == 0 {
					return fmt.Errorf("cookie %s not found", input.SecurityScheme.Name)
				}
				if len(cookieValues) > 1 {
					return fmt.Errorf("multiple cookies with name %s found", input.SecurityScheme.Name)
				}
				authTokenValue = cookieValues[0].Value
			default:
				return fmt.Errorf("unsupported apiKey location %s", input.SecurityScheme.In)
			}
		case "oauth2", "openIdConnect":
			if unsupportedPolicy == PolicyIgnore {
				return nil
			}
			return fmt.Errorf("%s security scheme not supported", input.SecurityScheme.Type)
		default:
			if unsupportedPolicy == PolicyIgnore {
				return nil
			}
			return fmt.Errorf("unsupported security scheme type %s", input.SecurityScheme.Type)
		}
		if authTokenValue == "" {
			return errors.New("auth token is required but not provided")
		}

		return nil
	}

View on GitHub (pinned to 909b515798)

Solutions

Fix the security scheme in the OpenAPI schema so apiKey 'in' is exactly one of: query, header, cookie.
Set the validator's OnUnsupportedSecurityScheme option to PolicyIgnore ("ignore") so unsupported schemes are skipped instead of failing requests.
Change the scheme type to http bearer/basic if clients actually authenticate via the Authorization header.
Re-load the schema with RequestValidator.LoadSchema after fixing, under a new or the same ref.

Example fix

// before (openapi yaml)
securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: headers   # typo, not query/header/cookie
    name: X-API-Key

// after
securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key

Defensive patterns

Strategy: validation

Validate before calling

// before LoadSchema: scan spec for apiKey locations
for _, sr := range doc.Components.SecuritySchemes {
    if sr.Value != nil && sr.Value.Type == "apiKey" &&
       sr.Value.In != "query" && sr.Value.In != "header" && sr.Value.In != "cookie" {
        return fmt.Errorf("scheme %q: unsupported apiKey location %q", sr.Value.Name, sr.Value.In)
    }
}

Type guard

func validApiKeyIn(in string) bool { return in == "query" || in == "header" || in == "cookie" }

Try / catch

if err := rv.LoadSchema(ref, schema, opts); err != nil {
    if strings.Contains(err.Error(), "unsupported apiKey location") {
        log.Errorf("fix the securitySchemes section: %v", err)
    }
    return err
}

Prevention

Only use query/header/cookie for apiKey 'in' in specs enforced by the WAF
Validate specs with an OpenAPI linter in CI before deployment
Prefer http bearer schemes for header-based API keys

When it happens

Trigger: A request hits a route secured by an apiKey security scheme whose SecurityScheme.In is not one of query/header/cookie — e.g. a hand-edited or generated OpenAPI spec using a non-standard location value — and the on_unsupported_security_scheme policy does not resolve to ignore.

Common situations: Custom or code-generated OpenAPI specs with an invalid 'in' enum value (typos like 'headers', 'cookies', 'body'); schemas written for a different gateway that supports apiKey in other locations; copy-pasted scheme definitions with casing mistakes.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/99e8c2fb2793236c. Report an issue: GitHub.