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 {@code ApiKeySecurityScheme} with the resolved scopes to the {@code Exchange}. Scopes can be checked in later plugins using the SpEL function {@code 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 {@code 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

NameRequiredDefaultDescriptionExample
required false true
 Controls whether API key validation is enforced. If set to {@code false}, the interceptor still extracts keys and loads scopes so they remain available for downstream checks (e.g., via {@code hasScope("...")}), but requests without a valid key are allowed to pass.
false

Child Elements

ElementsDescriptionCardinality
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:
0..*
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:
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:
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:
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 {@code X-Api-Key} is used.Default: (header name {@code X-Api-Key}) Examples:
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 {@code X-Api-Key} is used.Default: (header name {@code X-Api-Key}) Examples:
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 {@code X-Api-Key} is used.Default: (header name {@code X-Api-Key}) Examples:
0..*