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("...").

Typical configuration:

<api>
   <apiKey required="true">
     <!-- one or more key stores -->
     ...

     <!-- optional: customize extraction (header/query) -->
     <headerExtractor name="X-Api-Key"/>
   </apiKey>
 </api>

On missing or invalid keys, a Problem Details response is generated (401 for missing, 403 for invalid) unless required="false" is set.

Attributes

Name	Required	Default	Description	Examples
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 Elements

Element	Description	Cardinality
apiKeyFileStore	Loads API keys and optional scopes from a text file. Each non-empty line must contain a key.	0..*
databaseApiKeyStore	JDBC database store for API keys and their associated scopes. Uses two tables:	0..*
expressionExtractor	Extracts an API key by evaluating an expression on the incoming request. The result (a string) is treated as the API key. The expression is evaluated in the configured language (default: `SPEL`) during the request flow.	0..*
headerExtractor	Extracts an API key from a specific HTTP request header. By default, the header name is `X-Api-Key`. If the header is present, its first value is returned as the API key.	0..*
keys	Stores api keys inline as XML.	0..*
mongoDBApiKeyStore	Uses a MongoDB collection as a store for API keys and their scopes. Each document in the collection must use the API key as its `_id}` and may define an array field `scopes` listing the allowed scopes.	0..*
queryParamExtractor	Extracts an API key from a URL query parameter. By default, the parameter name is `api-key`. If the parameter is present in the request URI, its value is returned as the API key. Parameter name matching is case-insensitive.	0..*

Can be used in

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