3. Security and Validation

apiKey

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

     
     <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.


Can be used in:

serviceProxy, api, global, chainDef, for, stompProxy, if, registration, wsStompReassembler, internal, interceptor, chain, bean, transport and soapProxy

Syntax

<api port="2000">
  <openapi location="fruitshop-api-v2-openapi-3-security.yml" validateSecurity="yes"/>
  <apiKey required = "false">
    <headerExtractor name="X-Api-Key"/>
  </apiKey>
  <!--Swagger UI requires CORS but FruitShop does not use CORS, so we disable CORS.-->
  <headerFilter>
    <exclude>Origin</exclude>
  </headerFilter>
</api>

Attributes

NameRequiredDefaultDescriptionExamples
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

ElementsDescriptionCardinality
databaseApiKeyStore 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. Example: 
<apiKey>
   
   <yourFileStore src="classpath:keys.txt"/>
   <yourXmlStore  ref="sharedKeysBean"/>;
 </apiKey>
 0..*
mongoDBApiKeyStore 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. Example: 
<apiKey>
   
   <yourFileStore src="classpath:keys.txt"/>
   <yourXmlStore  ref="sharedKeysBean"/>;
 </apiKey>
 0..*
apiKeyFileStore 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. Example: 
<apiKey>
   
   <yourFileStore src="classpath:keys.txt"/>
   <yourXmlStore  ref="sharedKeysBean"/>;
 </apiKey>
 0..*
keys 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. Example: 
<apiKey>
   
   <yourFileStore src="classpath:keys.txt"/>
   <yourXmlStore  ref="sharedKeysBean"/>;
 </apiKey>
 0..*
expressionExtractor 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.Default: <headerExtractor /> (header name X-Api-Key) Examples: 
<apiKey>
   
   <headerExtractor />

   
   <headerExtractor name="Authorization" prefix="Api-Key "/>

   
   <queryParamExtractor name="api_key"/>
 </apiKey>
 0..*
queryParamExtractor 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.Default: <headerExtractor /> (header name X-Api-Key) Examples: 
<apiKey>
   
   <headerExtractor />

   
   <headerExtractor name="Authorization" prefix="Api-Key "/>

   
   <queryParamExtractor name="api_key"/>
 </apiKey>
 0..*
headerExtractor 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.Default: <headerExtractor /> (header name X-Api-Key) Examples: 
<apiKey>
   
   <headerExtractor />

   
   <headerExtractor name="Authorization" prefix="Api-Key "/>

   
   <queryParamExtractor name="api_key"/>
 </apiKey>
 0..*