RateLimit defines gateway-level rate limiting with configurable key sources. Sentinel delegates rate limit state to Unkey’s distributed rate limiting service, providing consistent counts across multiple sentinel instances.
RateLimit is defined in the policy schema but is not executed by the sentinel engine yet.
Fields
Maximum number of requests allowed in the time window.
Time window in milliseconds. For example, limit: 100 with window_ms: 60000 means 100 requests per minute.
Determines how requests are bucketed for rate limiting.
Examples
{
"policies": [
{
"id": "global-ratelimit",
"name": "Rate limit by IP",
"enabled": true,
"match": [],
"ratelimit": {
"limit": 1000,
"window_ms": 60000,
"key": { "remote_ip": {} }
}
}
]
}
{
"policies": [
{
"id": "user-ratelimit",
"name": "Rate limit per user",
"enabled": true,
"match": [],
"ratelimit": {
"limit": 500,
"window_ms": 60000,
"key": { "authenticated_subject": {} }
}
}
]
}
{
"policies": [
{
"id": "org-ratelimit",
"name": "Rate limit per organization",
"enabled": true,
"match": [],
"ratelimit": {
"limit": 10000,
"window_ms": 60000,
"key": { "principal_claim": { "claim_name": "org_id" } }
}
}
]
}
org_id claim.{
"policies": [
{
"id": "path-ratelimit",
"name": "Rate limit per endpoint",
"enabled": true,
"match": [
{ "path": { "path": { "prefix": "/v1/" } } }
],
"ratelimit": {
"limit": 100,
"window_ms": 60000,
"key": { "path": {} }
}
}
]
}
Key sources
| Source | Description |
|---|
remote_ip | Client IP address. Effective for anonymous traffic, but can over-limit behind shared NATs. |
header | Value of a named request header. Only use behind trusted proxies that set the header. |
authenticated_subject | Principal subject from an upstream auth policy. Most accurate for authenticated APIs. |
path | Request URL path. Creates a separate bucket per endpoint. |
principal_claim | Named claim from the Principal’s claims map (for example, org_id for per-organization limits). |
