> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RateLimit

> Gateway rate limiting (schema only)

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.

<Note>
  RateLimit is defined in the policy schema but is not executed by the sentinel engine yet.
</Note>

## Fields

<ResponseField name="limit" type="int64">
  Maximum number of requests allowed in the time window.
</ResponseField>

<ResponseField name="window_ms" type="int64">
  Time window in milliseconds. For example, `limit: 100` with `window_ms: 60000` means 100 requests per minute.
</ResponseField>

<ResponseField name="identifier" type="RateLimitIdentifier">
  Determines how requests are bucketed for rate limiting.
</ResponseField>

## Examples

<Tabs>
  <Tab title="Per IP">
    ```json theme={"theme":"kanagawa-wave"}
    {
      "policies": [
        {
          "id": "global-ratelimit",
          "name": "Rate limit by IP",
          "enabled": true,
          "match": [],
          "ratelimit": {
            "limit": 1000,
            "window_ms": 60000,
            "identifier": { "remote_ip": {} }
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Per authenticated subject">
    ```json theme={"theme":"kanagawa-wave"}
    {
      "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.
  </Tab>

  <Tab title="Per header value">
    ```json theme={"theme":"kanagawa-wave"}
    {
      "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.
  </Tab>

  <Tab title="Per principal field">
    ```json theme={"theme":"kanagawa-wave"}
    {
      "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.
  </Tab>

  <Tab title="Per path">
    ```json theme={"theme":"kanagawa-wave"}
    {
      "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.
  </Tab>
</Tabs>

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