key-auth

key-auth

Authenticates requests by matching an API key against a configured list of valid keys. Place it early in the request pipeline, before the upstream node, so unauthenticated requests never reach your backend.

Configuration

Key	Type	Default	Description
keys	array of strings	—	Exact-match list of accepted API keys, checked first. Required unless use_consumers is on: with neither, policy compilation fails.
header_name	string	x-api-key	Header the key is read from (compared case-insensitively).
query_param	string	unset	Query parameter checked as a fallback when the header is absent. No fallback if unset.
use_consumers	bool	false	Also accept keys declared on consumers (consumers[].credentials), setting consumer_name/consumer_group_id on a match. With it on, keys may be empty; with it off, an empty keys list fails policy compilation.
anonymous_consumer	string	unset	Name of a declared consumer to fall back to when no key matches: the request continues tagged as that consumer instead of taking the denied port. A name that matches no consumer is ignored, and the request is denied as usual.
hide_credentials	bool	false	Strip the key from the request (header and query parameter) before it reaches the upstream.

- id: auth
  type: key-auth
  config:
    keys: ["key-one", "key-two"]
    header_name: x-api-key
    query_param: api_key

Note: the UI node editor exposes keys and header_name only; set query_param directly in YAML.

Behavior

The plugin reads the key from header_name first, then falls back to query_param if configured. If the key matches an entry in keys, the context passes through the success port unchanged.

Unlike the other auth plugins, key-auth does not write any identity information into context.message — a valid key simply lets the request continue.

On a missing or invalid key the plugin sets a rejection on the response and exits through the denied port:

• context.response.status_code = 401
• Body: {"error": "unauthorized", "message": "Invalid or missing API key"} with content-type: application/json

Ports

key-auth declares three output ports: success, denied (a rejection is prepared), and error (never actually used — the plugin never fails). Like success, denied is a mandatory port: the policy compiler rejects any policy that leaves it unwired. Wire key-auth.denied straight to client so the prepared 401 reaches the caller instead of continuing into upstream:

edges:
  - from: key-auth.success
    to: upstream.in
  - from: key-auth.denied
    to: client.in

Errors

This node never fails at execution time: it always returns through success, so its error port is never taken.