Validates API keys extracted from incoming requests and looks up permissions (scopes) via configured key stores. Extractors can read the keys from HTTP headers, query parameters and may other message part. When validation succeeds, the interceptor adds an ApiKeySecurityScheme with the resolved scopes to the Exchange. Scopes can be checked in later plugins using the SpEL function hasScope("..."). On missing or invalid keys, a Problem Details response is generated (401 for missing, 403 for invalid) unless required="false" is set.

api:
  port: 2000
  flow:
    - apiKey:
       required: true
       extractors:
         - header:
             name: X-Api-Key

api:
  port: 2000
  flow:
    - apiKey:
       required: true
       extractors:
         - header:
             name: X-Api-Key

Syntax

apiKey:
  '$ref': <string>
  extractors:
    - <extractors>
  required: <boolean>
  stores:
    - <stores>

apiKey:
  '$ref': <string>
  extractors:
    - <extractors>
  required: <boolean>
  stores:
    - <stores>

Attributes

Name	Required	Default	Description	Examples
$ref	false	-	Reference a component defined under components.	-
required	false	true	Controls whether API key validation is enforced. If set to `false`, the interceptor still extracts keys and loads scopes so they remain available for downstream checks (e.g., via `hasScope("...")`), but requests without a valid key are allowed to pass.	false

Child Structure

Element	Cardinality	Description
extractors	0..*	Configures how and where API keys are extracted from requests (e.g., HTTP header or URL query parameter). Provide one or more extractor elements. If omitted, a header extractor using `X-Api-Key` is used.
stores	0..*	Defines the API key stores used to resolve and authorize keys. Provide one or more child elements that implement a store (e.g., file-based, in-memory. jdbc or mongodb). Scopes from multiple stores are combined.

Can be used in

abort api case chain components for global if interceptor internal otherwise proxy registration request response serviceProxy soapProxy stompProxy time transport wsStompReassembler