RateLimit

RateLimit defines gateway-level rate limiting with configurable identifiers. 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

limit

int64

Maximum number of requests allowed in the time window.

window_ms

int64

Time window in milliseconds. For example, limit: 100 with window_ms: 60000 means 100 requests per minute.

identifier

RateLimitIdentifier

Determines how requests are bucketed for rate limiting.

Examples

Per IP
Per authenticated subject
Per header value
Per principal field
Per path

{
  "policies": [
    {
      "id": "global-ratelimit",
      "name": "Rate limit by IP",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 1000,
        "window_ms": 60000,
        "identifier": { "remote_ip": {} }
      }
    }
  ]
}

{
  "policies": [
    {
      "id": "user-ratelimit",
      "name": "Rate limit per user",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 500,
        "window_ms": 60000,
        "identifier": { "authenticated_subject": {} }
      }
    }
  ]
}

Requires a KeyAuth or JWTAuth policy earlier in the list to set the Principal.

{
  "policies": [
    {
      "id": "tenant-ratelimit",
      "name": "Rate limit per tenant",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 5000,
        "window_ms": 60000,
        "identifier": { "header": { "name": "X-Tenant-Id" } }
      }
    }
  ]
}

Use only when the header is set by a trusted upstream proxy.

{
  "policies": [
    {
      "id": "org-ratelimit",
      "name": "Rate limit per organization",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 10000,
        "window_ms": 60000,
        "identifier": { "principal_field": { "path": "source.key.meta.org_id" } }
      }
    }
  ]
}

Creates a shared bucket for all keys that resolve to the same org_id meta value. The path is a dotted route into the Principal JSON — for JWT-authenticated traffic you might use source.jwt.payload.org_id instead.

{
  "policies": [
    {
      "id": "path-ratelimit",
      "name": "Rate limit per endpoint",
      "enabled": true,
      "match": [
        { "path": { "path": { "prefix": "/v1/" } } }
      ],
      "ratelimit": {
        "limit": 100,
        "window_ms": 60000,
        "identifier": { "path": {} }
      }
    }
  ]
}

Creates a separate bucket per URL path, protecting expensive endpoints without a separate policy for each.

Identifier 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_field`	Value resolved from a dotted path into the Principal JSON (for example, `source.key.meta.org_id` for per-organization limits).

Overview

Services

RFCs

Fields

Examples

Identifier sources

Overview

Services

RFCs

Documentation Index

​Fields

​Examples

​Identifier sources

Fields

Examples

Identifier sources