RateLimit

RateLimit defines gateway-level rate limiting with configurable identifiers. Frontline executes RateLimit policies and delegates counter state to rate limiting, so policy execution uses the same distributed counters as API and Frontline rate-limit checks.

Fields

int64

Maximum number of requests allowed in the time window.

int64

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

RateLimitIdentifier[]

Ordered list of 1 to 5 sources that form the rate limit key. Each unique combination of resolved values gets its own counter with the same limit and window.

RateLimitIdentifier

deprecated

Deprecated single-source form. Frontline still reads it from policies stored before compound identifiers existed; the API normalizes all writes to identifiers.

Examples

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

{
  "policies": [
    {
      "id": "user-ratelimit",
      "name": "Rate limit per user",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 500,
        "window_ms": 60000,
        "identifiers": [{ "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,
        "identifiers": [{ "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,
        "identifiers": [{ "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,
        "identifiers": [{ "path": {} }]
      }
    }
  ]
}

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

{
  "policies": [
    {
      "id": "subject-path-ratelimit",
      "name": "Rate limit per user per endpoint",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 100,
        "window_ms": 60000,
        "identifiers": [
          { "authenticated_subject": {} },
          { "path": {} }
        ]
      }
    }
  ]
}

A compound key: each subject gets a separate counter on each path. Parts join with : after escaping, so tuple boundaries stay unambiguous.

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

​Fields

​Examples

​Identifier sources

Fields

Examples

Identifier sources