Use config.identifier to choose what the Policy aggregates counters against:
|
Value
|
Description
|
consumer
|
The authenticated AI Consumer. This is the default.
|
consumer-group
|
The AI Consumer Group the AI Consumer belongs to. The Policy must be referenced from an AI Consumer Group to use this value.
|
credential
|
The credential the AI Consumer authenticated with. Use this to limit each API key separately when one AI Consumer holds several.
|
ip
|
The client IP address. See Limit by IP address.
|
header
|
The value of the header named in config.header_name.
|
path
|
The request path set in config.path.
|
To key counters on a combination of values, set config.compound_identifier to an array instead, for example ["ip", "consumer"]. When compound_identifier is set, it takes priority over identifier.
If limiting by IP address, it’s important to understand how AI Gateway determines the IP address of an incoming request.
The IP address is extracted from the request headers sent to AI Gateway by downstream clients. Typically, these headers are named X-Real-IP or X-Forwarded-For.
By default, AI Gateway uses the header name X-Real-IP to identify the client’s IP address. If your environment requires a different header, you can specify this by setting the real_ip_header Nginx property. Depending on your network setup, you may also need to configure the trusted_ips Nginx property to include the load balancer IP address. This ensures that AI Gateway correctly interprets the client’s IP address, even when the request passes through multiple network layers.
When config.identifier is consumer, use config.counter_key to control which AI Consumer attribute keys the rate limit counter. By default, the counter is keyed by consumer.id. You can also key by consumer.username or consumer.custom_id.
When you use consumer.username or consumer.custom_id, AI Consumers with identical attribute values contribute to the same rate limit counter, even if they were authenticated by different control planes. This enables consistent rate limiting across distributed deployments that share a Redis backend.
counter_key also applies when using compound_identifier with a Consumer segment, for example ["ip", "consumer"].
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $KONNECT_TOKEN" \
--data '
{
"display_name": "Rate Limiting Advanced - Consumer Username",
"name": "rate-limiting-advanced-counter-key",
"type": "rate-limiting-advanced",
"enabled": true,
"global": true,
"config": {
"identifier": "consumer",
"counter_key": "consumer.username",
"strategy": "redis",
"redis": {
"host": "'$REDIS_HOST'",
"port": 6379
},
"sync_rate": 10,
"limit": [
10
],
"window_size": [
60
]
}
}
'
ai_gateway_policies:
- ref: rate-limiting-advanced-counter-key
ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
display_name: Rate Limiting Advanced - Consumer Username
name: rate-limiting-advanced-counter-key
type: rate-limiting-advanced
enabled: true
global: true
config:
identifier: consumer
counter_key: consumer.username
strategy: redis
redis:
host: !env REDIS_HOST
port: 6379
sync_rate: 10
limit:
- 10
window_size:
- 60
Make sure to replace the following placeholders with your own values:
This example rate limits AI Consumers with the same username to a single shared counter, regardless of which control plane processed the request.
Set config.identifier to principal to rate limit based on the authenticated Kong Identity Principal instead of the AI Consumer, credential, IP address, or other supported identifiers. principal is also a valid segment in config.compound_identifier.
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $KONNECT_TOKEN" \
--data '
{
"display_name": "Rate Limiting Advanced - Principal",
"name": "rate-limiting-advanced-principal",
"type": "rate-limiting-advanced",
"enabled": true,
"global": true,
"config": {
"identifier": "principal",
"limit": [
10
],
"window_size": [
60
]
}
}
'
ai_gateway_policies:
- ref: rate-limiting-advanced-principal
ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
display_name: Rate Limiting Advanced - Principal
name: rate-limiting-advanced-principal
type: rate-limiting-advanced
enabled: true
global: true
config:
identifier: principal
limit:
- 10
window_size:
- 60
Make sure to replace the following placeholders with your own values:
AI_GATEWAY_ID: The id of your AI Gateway.
principal requires an AI Auth Strategy that populates the Principal, for example, an openid-connect or key-auth AI Auth Strategy configured with Kong Identity Principal mapping.
config.custom_key overrides the computed rate limiting key with a literal string, regardless of identifier or compound_identifier. This is most useful in combination with expressible config fields, where custom_key’s value comes from a CEL expression instead of a fixed string.
limit and custom_key accept a CEL expression. Set the expressions in the Policy’s top-level expressions object, alongside config. If an expression is set, AI Gateway evaluates it on each request and uses the result as the field’s value, for example an attribute of the authenticated AI Consumer or Principal. If the expression fails to evaluate, AI Gateway uses the static value in config.
Because limit is an array field (one value per configured window), its expression is also an array, with one expression per element, in the same order:
curl -X POST "https://us.api.konghq.com/v1/ai-gateways/$AI_GATEWAY_ID/policies" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN"\
-H "Content-Type: application/json" \
--json '{
"name": "rate-limiting-advanced-principal-metadata",
"display_name": "Rate Limiting Advanced - Principal Metadata",
"type": "rate-limiting-advanced",
"enabled": true,
"global": true,
"config": {
"identifier": "principal",
"custom_key": "unknown-partner",
"limit": [
10
],
"window_size": [
60
]
},
"expressions": {
"custom_key": "principal.metadata.partner_id",
"limit": [
"principal.metadata.rate_limit"
]
}
}'
In this example, custom_key and limit are static fallback values used only if the corresponding CEL expression is unset, invalid, or fails to evaluate.
Note: window_size is not expressible because it’s unreliable. For the cluster and redis strategies, window sizes are registered for cross-node counter synchronization once, from the static config, when the Policy is configured. A per-request expression-driven window size would never be picked up by that registration.