Quota tiers

A quota tier is a named, reusable set of rate limiting rules. Instead of configuring the same limits on each security definition one by one, you define the limits once, give them a name - Bronze, Silver, Gold - and assign that name to as many API clients as needed.

A tier is stored once and referenced by name, so the same limits govern any number of consumers:

• Define a plan once and apply it to hundreds of API clients
• Change the plan in one place and every client that references it picks up the new limits immediately
• Assign a tier to a whole security group so every member follows the same plan

Counting stays per consumer - clients on the same tier never share counters - and clients see their allowance through the X-RateLimit-Limit and X-RateLimit-Remaining response headers.

Tiers vs. direct rate limiting

A tier holds the same rules that the rate limiting editor produces - address lists, time ranges, rate, burst, limit and time unit. The difference is reuse:

• Direct rules belong to one security definition or one channel and are edited there
• A tier is a standalone object that definitions and groups reference by name

A security definition either references a tier or has its own rules - never both. Its own rules, when present, always take precedence over any tier.

REST and SOAP channels follow the same rule - a channel either references a tier or has its own rules, never both. Both levels still stack - a request must pass the security definition's tier or rules first and the channel's tier or rules next.

Define a tier

In Dashboard, navigate to Security -> Quota tiers and click Create a quota tier.

The editor is the same rule builder as for rate limiting - one or more rules, each with an address list and time ranges holding rate, burst, limit and time unit. Give the tier a name and, optionally, a description, then save.

The tier list shows each tier's limits at a glance along with how many definitions and groups reference it. You cannot delete a tier that is still referenced.

Assign a tier to a security definition or a channel

Open the Rate limiting link of a Basic Auth or API key definition, or of a REST or SOAP channel. At the top of the page there are two tabs:

• Quota tier - pick a tier from the select and the definition or channel follows the tier's rules - the page hides the rule builder
• Custom rules - the page shows the rule builder and the definition or channel has its own rules

If no tiers have been defined yet, the Quota tier tab offers a Create one button that opens the tier editor.

Counters are always tracked per security definition. Two definitions on the same Gold tier each get the full Gold allowance - each keeps its own counters.

Assign a tier to a security group

A tier set on a security group applies to every member of that group, again with per-member counting. In the group's create or edit dialog, pick the tier from the Quota tier select.

Precedence, from strongest to weakest:

1. A definition's own custom rules
2. A tier assigned directly to the definition
3. A tier assigned to a group that the definition belongs to

Group membership changes take effect immediately - adding a member to a group with a tier puts that member on the tier's plan, unless it has its own rules or its own tier.

Response headers

Requests governed by a security definition's limits - whether from a tier or from custom rules - receive two response headers:

$ curl -v http://user:password@localhost:17010/api/customer

< HTTP/1.1 200 OK
< X-RateLimit-Limit: 1000
< X-RateLimit-Remaining: 993

• X-RateLimit-Limit - the total allowance of the most constrained matching limit
• X-RateLimit-Remaining - how much of that allowance is left

When the limit is exhausted, the headers accompany the 429 response next to the existing Retry-After:

$ curl -v http://user:password@localhost:17010/api/customer

< HTTP/1.1 429 Too Many Requests
< Retry-After: Mon, 01 Jun 2026 00:00:00 GMT
< X-RateLimit-Limit: 1000
< X-RateLimit-Remaining: 0

Channel-level limits add no headers - the headers describe the consumer's allowance only.

Enmasse

You define and assign tiers in enmasse YAML too. The top-level quota_tier list defines the tiers, and security and groups entries reference them by name through a quota_tier key:

quota_tier:
  - name: Gold
    description: Premium partners
    rules:
      - cidr_list:
          - 0.0.0.0/0
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 100
            burst: 200
            limit: 100000
            limit_unit: month

security:
  - name: partner.credentials
    type: basic_auth
    username: partner1
    quota_tier: Gold

groups:
  - name: premium.partners
    quota_tier: Gold
    members:
      - partner.credentials

Enmasse rejects a security definition with both quota_tier and rate_limiting at import time - the two are mutually exclusive.

See also

Learn more