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

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

​Fields

​Examples

​Identifier sources

Fields

Examples

Identifier sources