# Quota tiers

Named rate-limit plans - define Bronze, Silver and Gold once and assign them to any number of API clients.

## Overview {#overview}

A quota tier is a named, reusable set of [rate limiting](https://zato.io/docs/admin/guide/rate-limit.html) 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. Changing the plan in one place updates every client that references it, immediately and without restarts.

Counting stays per consumer - two definitions on the same Gold tier each get the full Gold allowance with their own counters - and clients see their allowance through the `X-RateLimit-Limit` and `X-RateLimit-Remaining` response headers.

Tiers are managed in the dashboard under **Security** > **Quota tiers**.

## Definition fields {#definition-fields}

| Field | Notes |
| --- | --- |
| Name | A unique name for the tier - the name definitions and groups reference |
| Description | Optional free-form text describing the plan |
| Rules | One or more rules, each with an address list and time ranges holding rate, burst, limit and time unit - the same rule builder as for [rate limiting](https://zato.io/docs/admin/guide/rate-limit.html) |

The tier list shows each tier's limits along with the number of definitions and groups that reference it - a tier that is still referenced cannot be deleted.

Tiers are exported and imported with [enmasse](https://zato.io/docs/admin/enmasse.html) under the top-level `quota_tier` key, and definitions and groups reference them by name through a `quota_tier` entry - the fields are in the [enmasse reference](https://zato.io/docs/admin/enmasse-reference.html).

## Security definitions and channels {#security-definitions-and-channels}

Open the **Rate limiting** link of a [Basic Auth](https://zato.io/docs/security/basic-auth.html) or [API key](https://zato.io/docs/security/api-keys.html) definition, or of a [REST](https://zato.io/docs/dev/rest/channels.html) 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
- **Custom rules** - the definition or channel has its own rules, edited in place

A definition or channel either references a tier or has its own rules - never both. Both levels still stack - a request must pass the channel's tier or rules first, before the caller is authenticated, and the security definition's tier or rules next.

## Security groups {#security-groups}

A tier set on a [security group](https://zato.io/docs/security/groups.html) 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

## Response headers {#response-headers}

Requests governed by a consumer's limits receive the `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers, and an exhausted allowance answers with 429 and `Retry-After` - the details, including the header semantics and the full request flow, are under [quota tiers in the administration guide](https://zato.io/docs/admin/guide/quota-tiers.html).

## Learn more {#learn-more}

- [Securing channels](https://zato.io/docs/admin/security/channel.html) - Which security types a channel accepts, and how to assign them
- [Securing outgoing connections](https://zato.io/docs/admin/security/outgoing.html) - Credentials Zato presents to the systems it calls
- [API keys](https://zato.io/docs/security/api-keys.html) - Per-client keys in a configurable HTTP header
- [Basic Auth](https://zato.io/docs/security/basic-auth.html) - Usernames and passwords for channels and outgoing connections
- [Bearer tokens](https://zato.io/docs/security/bearer-tokens/) - Static tokens and JWTs verified against a JWKS endpoint
- [Security groups](https://zato.io/docs/security/groups.html) - Many API client credentials on one channel or MCP gateway
- [Kerberos (SPNEGO)](https://zato.io/docs/security/kerberos/) - Negotiate authentication from a keytab, with no ticket management
- [mTLS](https://zato.io/docs/security/mtls/) - Client certificates in both directions, matched by fingerprint or DN
- [NTLM](https://zato.io/docs/security/ntlm.html) - Windows domain credentials for outgoing connections
- [WS-Security](https://zato.io/docs/security/ws-security.html) - UsernameToken, X.509 and SAML for SOAP traffic
- [TLS certificates](https://zato.io/docs/admin/security/ssl/) - Your own certificates, the self-signed ones and how to rotate them