You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add internal documentation links for key concepts and terms that are
introduced or mentioned without explanation:
- Link "Security Policy" to /api-management/policies
- Link "rate limiting" and "Rate Limits" to /api-management/rate-limit
- Link "Redis" to /tyk-configuration-reference/redis-cluster-sentinel
- Link "Access Keys" to /api-management/policies#access-key
These cross-references help users navigate to related documentation
and better understand the relationships between quotas, rate limiting,
policies, and the underlying infrastructure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
Validate that all newly added internal links resolve to the correct pages and anchors (policies, rate-limit, redis-cluster-sentinel, policies#access-key) in the deployed docs site and match current routes/anchors.
Request Quotas in Tyk Gateway allow you to set a maximum number of API requests for a specific API key or [Security Policy](/api-management/policies) over longer, defined periods (e.g., day, week, month). This feature is distinct from [rate limiting](/api-management/rate-limit) (which controls requests per second), and it is essential for managing API consumption, enforcing service tiers, and protecting your backend services from sustained overuse over time.
```mermaid
flowchart LR
Client[API Client] -->|Makes Request| Gateway[Tyk Gateway]
Gateway -->|Check Quota| Redis[(Redis)]
Redis -->|Quota OK| Gateway
Redis -->|Quota Exceeded| Gateway
Gateway -->|If Quota OK| Upstream[Upstream API]
Gateway -->|If Quota Exceeded| Reject[Reject Request]
Upstream -->|Response| Gateway
Gateway -->|Response| Client
Key Benefits
Enforce Usage Limits: Cap the total number of requests allowed over extended periods (days, weeks, months) per consumer.
Implement Tiered Access: Easily define different usage allowances for various subscription plans (e.g., Free, Basic, Pro).
Protect Backend Services: Prevent individual consumers from overwhelming upstream services with consistently high volume over long durations.
Enable Usage-Based Monetization: Provide a clear mechanism for charging based on consumption tiers.
Quick Start
Overview
In this tutorial, we will configure Request Quotas on a Tyk Security Policy to limit the number of requests an API key can make over a defined period. Unlike rate limits (requests per second), quotas control overall volume. We'll set a low quota limit with a short renewal period for easy testing, associate a key with the policy, observe blocked requests once the quota is exhausted, and verify that the quota resets after the period elapses. This guide primarily uses the Tyk Dashboard for configuration.
Prerequisites
Working Tyk Environment: You need access to a running Tyk instance that includes both the Tyk Gateway and Tyk Dashboard components. For setup instructions using Docker, please refer to the Tyk Quick Start.
Curl, Seq and Sleep: These tools will be used for testing.
Instructions
Create an API
Create an API:
Log in to your Tyk Dashboard.
Navigate to API Management > APIs
Click Add New API
Click Import
Select Import Type as Tyk API
Copy the below Tyk OAS definition in the text box and click Import API to create an API.
Create and Configure a Security Policy with a Request Quota:
1. Navigate to **API Security > Policies** in the Tyk Dashboard sidebar.
2. Click the **Add Policy** button.
3. Under the **1. Access Rights** tab, in the **Add API Access Rule** section, select the `Request Quota Test` API.
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* **Important:** Disable **[Rate Limiting](/api-management/rate-limit)** by selecting **Disable rate limiting** option, so it doesn't interfere with testing the quota.
* Set the following values for `Usage Quotas`:
* Uncheck the `Unlimited requests` checkbox
* Enter `10` into the **Max Requests per period** field. (This is our low quota limit for testing).
* Select `1 hour` from the **Quota resets every:** dropdown. (In the next step, we will modify it to 60 seconds via API for quick testing, as 1 hour is a very long period. From the dashboard, we can only select pre-configured options.)
5. Select the **2. Configuration** tab.
6. In the **Policy Name** field, enter `Request Quota Policy`.
7. From the **Key expire after** dropdown, select `1 hour`.
8. Click the **Create Policy** button.
Update Quota Reset Period via API:
As the Dashboard UI doesn't allow setting a shorter duration, we will set the Quota reset period to a value of 1 minute for testing purposes. The following commands search for the policy, modify its quota_renewal_rate to 60 seconds, and update the API.
Note: Obtain your Dashboard API key by clicking on the User profile at the top right corner, then click on Edit Profile, and select the key available under Tyk Dashboard API Access Credentials. Now in the below command replace <your-api-key> with the API key you obtained from the Dashboard UI.
1. Navigate to **API Security > Keys** in the Tyk Dashboard sidebar.
2. Click the **Add Key** button.
3. Under the **1. Access Rights** tab:
* In the **Apply Policy** section, select the `Request Quota Policy`.
4. Select the **2. Configuration** tab.
5. In the **Alias** field, enter `Request Quota Key`. This provides a human-readable identifier.
6. From the **Expires** dropdown, select `1 hour`.
7. Click the **Create Key** button.
8. A pop-up window **"Key created successfully"** will appear displaying the key details. **Copy the Key ID** value shown and save it securely. You will need this key to make API requests in the following steps.
9. Click **OK** to close the pop-up.
Testing
Test Quota Exhaustion:
We've set a quota of 10 requests per 60 seconds. Let's send more than 10 requests within that window to observe the quota being enforced.
Open your terminal.
Execute the following command, replacing <replace-with-key-id> with the API Key ID you saved earlier. This command attempts to send 15 requests sequentially.
(Note: The sleep 0.1 adds a tiny delay, but ensure all 15 requests execute well within the 60-second quota window).
Expected Observation: You should see the first 10 requests succeed, returning an HTTP status code 200. After the 10th request, the subsequent requests (11 through 15) should be blocked by the quota limit, returning an HTTP status code 403 (Forbidden).
Expected Observation: This request should now succeed, returning an HTTP status code 200. This demonstrates that because the 60-second quota period ended, the next request made after that period triggered the quota reset, replenishing the allowance.
Sample Output:
Waiting for quota to reset (70 seconds)...
Wait complete. Sending one more request...
200
This quick start demonstrates the fundamental behaviour of Request Quotas: they limit the total number of requests allowed within a specific period and automatically reset the allowance once that period renews (triggered by the next request).
Configuration Options
Request Quotas in Tyk can be configured at various levels.
The configuration involves setting two specific fields:
QuotaMax: The maximum number of requests allowed during the quota period.
Set to -1 for unlimited requests
Set to a positive integer (e.g., 1000) to limit total requests
QuotaRenewalRate: The time in seconds for which the quota applies.
Example: 3600 for the hourly quota (1 hour = 3600 seconds)
Example: 86400 for the daily quota (24 hours = 86400 seconds)
Example: 2592000 for the monthly quota (30 days = 2592000 seconds)
System-Level Configuration
Global quota settings are configured in the Tyk Gateway configuration file (tyk.conf). These settings affect how quotas are enforced across the entire gateway.
{/* Why we are commenting org quotas: Organization quotas are a hangover from the Classic Cloud, where all clients shared a deployment. They are not documented anywhere presently, and I’m not sure why we would start to do so - but if we’re going to, we need to be very careful not to add complexity to the way users configure things. */}
{/* ### Organization-Level Configuration
Organization quotas limit the total number of requests across all APIs for a specific organization. These are enforced by the OrganizationMonitor middleware when enforce_org_quotas is enabled.
quota_max: Maximum number of requests allowed during the quota period
quota_renewal_rate: Time in seconds for the quota period (e.g., 3600 for hourly quotas)
Organization quotas are configured through the Tyk Dashboard API or Gateway API:
curl -X POST -H "Authorization: {your-api-key}" \
-H "Content-Type: application/json" \
-d '{ "quota_max": 1000, "quota_renewal_rate": 3600, }' \
http://tyk-gateway:8080/tyk/org/keys/{org-id}
```*/}### API-Level ConfigurationYou **cannot set** quota values within an API Definition, but you can **disable** quota checking entirely for all requests proxied through that specific API, regardless of Key or Policy settings. This is useful if an API should never have quota limits applied.<Tabs><Tab title="Tyk OAS API Definition">In a Tyk OAS API Definition, you can globally disable quotas for specific APIs:- **skipQuota**: When set to true, disables quota enforcement for the API.- **skipQuotaReset**: When set to true, prevents quota counters from being reset when creating or updating quotas.```json{ // Partial config from Tyk OAS API Definition"middleware": {"global": {"skipQuota": true,"skipQuotaReset": false } }, // ... more config follows}
The Tyk Dashboard provides a straightforward interface to set request quota parameters on Security Policies and Access Keys.
The image below shows a policy with request quotas. Any key using this policy will inherit the quota settings and behave as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
1. Navigate to **API Security > Policies** in the Tyk Dashboard sidebar
2. Click the **Add Policy** button
3. Under the **1. Access Rights** tab and in the **Add API Access Rule** section, select the required API
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* Enable `Request Quotas` by setting the following values in the `Usage Quotas` section:
* Uncheck the `Unlimited Requests` checkbox
* Field **Requests (or connection attempts) per period** - Enter the total number of requests a client can use during the defined quota period.
* Field **Quota resets every:** - Select the duration of the quota period.
5. Select the **2. Configuration** tab
6. In the **Policy Name** field, enter a name
7. From the **Key expire after** dropdown, select an option
8. Click the **Create Policy** button
The image below shows an access key with request quotas. This access key behaves as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
Note: Direct key configuration overrides policy settings only for that specific key.
1. Navigate to **API Security > Keys** in the Tyk Dashboard sidebar
2. Click the **Create Key** button
3. Under the **1. Access Rights** tab:
* Select **Choose API**
* In the **Add API Access Rule** section, select the required API
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* Enable `Request Quotas` by setting the following values in the `Usage Quotas` section:
* Uncheck the `Unlimited Requests` checkbox
* Field **Requests (or connection attempts) per period** - Enter the total number of requests a client can use during the defined quota period.
* Field **Quota resets every:** - Select the duration of the quota period.
5. Select the **2. Configuration** tab
6. In the **Alias** field, enter a name. This human-readable identifier makes tracking and managing this specific access key easier in your analytics and logs.
7. From the **Expires** dropdown, select an option
8. Click the **Create Key** button
Configure via API
These are the fields that you can set directly in the Policy object or the Access Key:
{
// Partial policy/session object fields"quota_max": 1000, // Allow one thousand requests"quota_renewal_rate": 86400, // 1 day or 24 hours// ... more config follows
}
To update the policy, do the following:
Retrieve the policy object using GET /api/portal/policies/{POLICY_ID}
Add or modify the quota_max and quota_renewal_rate fields within the policy JSON object
Update the policy using PUT /api/portal/policies/{POLICY_ID} with the modified object, or create a new one using POST /api/portal/policies/
Explanation:
The above adds request quotas to a policy. Any key using this policy will inherit the quotas settings and behaves as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
Note: Direct key configuration overrides policy settings only for that specific key.
To update the access key do the following:
Retrieve the key's session object using GET /api/keys/{KEY_ID}
Add or modify the quota_max and quota_renewal_rate fields within the session object JSON
Update the key using PUT /api/keys/{KEY_ID} with the modified session object
Explanation:
The above adds quotas to an access key. Any request made by the key will behave as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
Important Considerations
Policy Precedence: Quotas set on a Security Policy apply to all keys using that policy unless overridden by a specific quota set directly on the key (using the "Set per API Limits and Quota" option).
Unlimited Quota: Setting quota_max to -1 grants unlimited requests for the quota period.
Event-Driven Resets: Quotas reset after the quota_renewal_rate (in seconds) has passed and upon the next request using the key. They do not reset automatically on a fixed schedule (e.g., precisely at midnight or the 1st of the month) unless external automation updates the session object.
Response Headers: When quotas are active, Tyk typically adds X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers to responses, allowing clients to track their usage. (Note: Header names might be configurable).
How It Works
Request Quotas in Tyk limit a client's total number of API requests within a defined period (hours, days, months). Unlike rate limits that control the frequency of requests over short intervals (like seconds or minutes) to prevent immediate system overload, Request Quotas control the total volume of requests allowed over much longer periods to manage overall consumption and align with service tiers.
When clients reach their quota limit, further requests are rejected until the quota period renews. It helps API providers implement usage-based pricing tiers, prevent API abuse, control infrastructure costs, and ensure fair resource distribution among clients.
Think of Request Quotas as a prepaid phone plan with a fixed number of minutes per month. When you sign up, you get allocated a specific number of call minutes (API requests) that you can use over the billing period. You can make calls (API requests) at any pace you want – all at once or spread throughout the month – but once you've used up your allocated minutes, you can't make any more calls until the next billing cycle begins.
Tyk implements request quotas using a Redis-based counter mechanism with time-based expiration. Here's a detailed breakdown of the implementation:
graph LR
A[API Request Received] --> B(Check Redis Quota Counter);
B -- Counter < QuotaMax --> C{Increment Redis Counter};
C --> D[Calculate quota_remaining = QuotaMax - Counter];
D --> E[Update Session State];
E --> F[Forward Request to Upstream];
B -- Counter >= QuotaMax --> G[Reject Request with 403];
Loading
Core Components
Redis Storage: Quotas are tracked in Redis using incrementing counters for each API key. The TTL is set to the quota renewal period, and the counter is reset to 0 on the next request after expiration.
Here is a sample Redis key for a Request Quota:
quota-[scope]-[key_hash]
Where:
- scope is optional and represents an API-specific allowance scope
- key_hash is the hashed API key (if hash keys are enabled)
Session State: Quota configuration is stored in the user's SessionState, which contains several quota-related fields:
QuotaMax: Maximum number of requests allowed during the quota period.
QuotaRemaining: Number of requests remaining for the current period. Note: This is a derived value, not the primary counter.
QuotaRenews: Unix timestamp when the quota will reset.
QuotaRenewalRate: Time in seconds for the quota period (e.g., 3600 for hourly quotas).
Middleware: The quota check is performed by the RateLimitAndQuotaCheck middleware
Quota Enforcement
The core logic for checking and enforcing Request Quotas is executed within the RateLimitAndQuotaCheck middleware, which is a step in the request processing pipeline. Here's a breakdown of this process:
Initiation: As a request enters the Tyk Gateway, it passes through configured middleware. The quota validation process begins when it hits the RateLimitAndQuotaCheck middleware.
Applicability Check: The middleware first determines if quota enforcement is relevant:
It checks the API Definition to see if quotas are globally disabled. If so, the process stops here for quotas and the request proceeds.
It identifies the API key for the request and retrieves its associated SessionState.
Retrieve Limits: The middleware accesses the SessionState to get the specific quota parameters applicable to this key and potentially the specific API being accessed (if per-API quotas are configured):
QuotaMax: The maximum number of requests allowed.
QuotaRenewalRate: The duration (in seconds) of the quota period for setting the TTL in Redis.
Redis Interaction & Enforcement: This is the core enforcement step, interacting directly with Redis:
Construct Key: Generates the unique Redis key for tracking this specific quota counter (e.g., quota-{scope}-{api-key-hash}).
Check Expiry/Existence: It checks Redis to see if the key exists and if its TTL is still valid.
Handle Renewal (If Expired/Missing): If the key doesn't exist or its TTL has passed, Tyk initiates the renewal logic described previously (attempting a distributed lock, setting the counter to 0, and applying the QuotaRenewalRate as the new TTL).
Increment Counter: Tyk atomically increments the Redis counter value. This operation returns the new value of the counter after the increment.
Compare Against Limit: The middleware compares this new counter value against the QuotaMax retrieved from the session state.
Decision:
If new_counter_value <= QuotaMax: The request is within the allowed quota.
If new_counter_value > QuotaMax: This request has exceeded the quota limit.
Outcome:
Quota OK: The middleware allows the request to proceed to the next stage in the processing pipeline (e.g., other middleware, upstream service).
Quota Exceeded: The middleware halts further request processing down the standard pipeline. It prepares and returns an error response to the client, typically HTTP 403 Forbidden with a "Quota exceeded" message.
Session State Update: Regardless of whether the request was allowed or blocked due to the quota, the middleware calls an internal function (like updateSessionQuota) to update the in-memory SessionState associated with the API key. This update synchronizes the QuotaRemaining field in the session with the latest calculated state based on the Redis counter and its expiry. It ensures that subsequent operations within the same request lifecycle (if any) or diagnostic information have access to the most recent quota status.
Quota Reset Mechanisms
The available allowance (QuotaRemaining) for an API key is replenished back to its maximum (QuotaMax) through several distinct mechanisms:
Event-Driven Renewal (Primary Mechanism):
Condition: This occurs after the time duration specified by QuotaRenewalRate (in seconds) has elapsed since the quota period began (i.e., since the last reset or key creation/update). In Redis, this corresponds to the Time-To-Live (TTL) expiring on the quota tracking key.
Trigger: The reset is not automatic based on a timer. It is triggered by the next API request made using that specific key after the QuotaRenewalRate duration has passed (and the Redis TTL has expired).
Process: Upon detecting the expired TTL during that next request, Tyk resets the Redis counter (typically by setting it to 0 and immediately incrementing it to 1 for the current request) and applies a new TTL based on the QuotaRenewalRate. This effectively makes the full QuotaMax available for the new period starting from that moment.
graph LR
A[Request After Quota Period] --> B{Redis Key Expired?};
B -- Yes --> C[Reset Counter to 0];
C --> D[Set New Expiration];
D --> E[Process Request Normally];
B -- No --> F[Continue Normal Processing];
Loading
Manual Reset via API:
Mechanism: You can force an immediate quota reset for a specific API key by calling an endpoint on the Tyk Gateway Admin API.
Effect: This action directly deletes the corresponding quota tracking key in Redis. The next request using this API key will find no existing key, triggering the renewal logic (Step 1) as if the period had just expired, immediately granting the full QuotaMax and setting a new TTL. This provides an immediate, on-demand refresh of the quota allowance.
Key Creation or Update:
Trigger: When a new API key is created or an existing key's configuration is updated (e.g., via the Dashboard or the Gateway API), Tyk reapplies the quota settings based on the current policy or key-specific configuration.
Process: This typically involves setting the QuotaRemaining value to QuotaMax in the key's session data and ensuring the corresponding Redis key is created with the correct initial value (or implicitly reset) and its TTL set according to the QuotaRenewalRate. This ensures the key starts with a fresh quota allowance according to its defined limits.
Exception: This behavior can be suppressed if the API definition includes the DontSetQuotasOnCreate field (referred to as SkipQuotaReset in the OAS specification), which prevents automatic quota resets during key creation or updates.
Key Technical Aspects
Time-Based Reset: Unlike rate limiting, which uses sliding windows, quotas have a fixed renewal time determined by QuotaRenewalRate (in seconds)
</details>
<details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/1098/files#diff-58a536d25b2b7189628d843380371c1b263909af63606716da471ea511eb60deR31-R616'><strong>Consistent Terminology</strong></a>
Ensure consistent capitalization and styling for “Request Quotas”, “Rate Limits”, “Security Policy/Policies”, and “Access Keys” across the page and linked contexts; check that pluralization and hyphenation match house style.
</summary>
```txt
---
## Quick Start
### Overview
In this tutorial, we will configure Request Quotas on a [Tyk Security Policy](/api-management/policies) to limit the number of requests an API key can make over a defined period. Unlike [rate limits](/api-management/rate-limit) (requests per second), quotas control overall volume. We'll set a low quota limit with a short renewal period for easy testing, associate a key with the policy, observe blocked requests once the quota is exhausted, and verify that the quota resets after the period elapses. This guide primarily uses the Tyk Dashboard for configuration.
### Prerequisites
- **Working Tyk Environment:** You need access to a running Tyk instance that includes both the Tyk Gateway and Tyk Dashboard components. For setup instructions using Docker, please refer to the [Tyk Quick Start](https://github.com/TykTechnologies/tyk-pro-docker-demo?tab=readme-ov-file#quick-start).
- **Curl, Seq and Sleep**: These tools will be used for testing.
### Instructions
#### Create an API
1. **Create an API:**
1. Log in to your Tyk Dashboard.
2. Navigate to **API Management > APIs**
3. Click **Add New API**
4. Click **Import**
5. Select **Import Type** as **Tyk API**
6. Copy the below Tyk OAS definition in the text box and click **Import API** to create an API.
<Expandable title='Click to expand API Definition'>
```json
{
"components": {
"securitySchemes": {
"authToken": {
"in": "header",
"name": "Authorization",
"type": "apiKey"
}
}
},
"info": {
"title": "Request Quota Test",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {},
"security": [
{
"authToken": []
}
],
"servers": [
{
"url": "http://tyk-gateway.localhost:8080/request-quota-test/"
}
],
"x-tyk-api-gateway": {
"info": {
"name": "Request Quota Test",
"state": {
"active": true
}
},
"middleware": {
"global": {
"contextVariables": {
"enabled": true
},
"trafficLogs": {
"enabled": true
}
}
},
"server": {
"authentication": {
"enabled": true,
"securitySchemes": {
"authToken": {
"enabled": true
}
}
},
"listenPath": {
"strip": true,
"value": "/request-quota-test/"
}
},
"upstream": {
"url": "http://httpbin.org/"
}
}
}
```
</Expandable>
#### Configure Policy and Quota
2. **Create and Configure a Security Policy with a Request Quota:**
<Expandable title='Click to expand to see detailed steps to configure a Request Quota in the Tyk Dashboard UI'>
1. Navigate to **API Security > Policies** in the Tyk Dashboard sidebar.
2. Click the **Add Policy** button.
3. Under the **1. Access Rights** tab, in the **Add API Access Rule** section, select the `Request Quota Test` API.
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* **Important:** Disable **[Rate Limiting](/api-management/rate-limit)** by selecting **Disable rate limiting** option, so it doesn't interfere with testing the quota.
* Set the following values for `Usage Quotas`:
* Uncheck the `Unlimited requests` checkbox
* Enter `10` into the **Max Requests per period** field. (This is our low quota limit for testing).
* Select `1 hour` from the **Quota resets every:** dropdown. (In the next step, we will modify it to 60 seconds via API for quick testing, as 1 hour is a very long period. From the dashboard, we can only select pre-configured options.)
5. Select the **2. Configuration** tab.
6. In the **Policy Name** field, enter `Request Quota Policy`.
7. From the **Key expire after** dropdown, select `1 hour`.
8. Click the **Create Policy** button.
</Expandable>
<img src="/img/dashboard/system-management/request-quotas-policy-quick-start.png" alt="policy with request quota configured" />
4. **Update Quota Reset Period via API:**
As the Dashboard UI doesn't allow setting a shorter duration, we will set the Quota reset period to a value of 1 minute for testing purposes. The following commands search for the policy, modify its `quota_renewal_rate` to 60 seconds, and update the API.
**Note:** Obtain your Dashboard API key by clicking on the User profile at the top right corner, then click on `Edit Profile`, and select the key available under `Tyk Dashboard API Access Credentials`. Now in the below command replace `<your-api-key>` with the API key you obtained from the Dashboard UI.
```
curl -s --location 'http://localhost:3000/api/portal/policies/search?q=Request%20Quota%20Policy' \
-H "Authorization: <your-api-key>" \
-H "Accept: application/json" > policy.json
jq '.Data[0] | .quota_renewal_rate = 60' policy.json > updated_policy.json
jq -r '.Data[0]._id' policy.json > policy_id.txt
curl --location "http://localhost:3000/api/portal/policies/$(cat policy_id.txt)" \
-H "Authorization: <your-api-key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X PUT \
-d @updated_policy.json
```
3. **Associate an Access Key with the Policy:**
<Expandable title='Click to expand to see detailed steps to Associate an Access Key with the Policy in the Tyk Dashboard UI'>
1. Navigate to **API Security > Keys** in the Tyk Dashboard sidebar.
2. Click the **Add Key** button.
3. Under the **1. Access Rights** tab:
* In the **Apply Policy** section, select the `Request Quota Policy`.
4. Select the **2. Configuration** tab.
5. In the **Alias** field, enter `Request Quota Key`. This provides a human-readable identifier.
6. From the **Expires** dropdown, select `1 hour`.
7. Click the **Create Key** button.
8. A pop-up window **"Key created successfully"** will appear displaying the key details. **Copy the Key ID** value shown and save it securely. You will need this key to make API requests in the following steps.
9. Click **OK** to close the pop-up.
</Expandable>
#### Testing
4. **Test Quota Exhaustion:**
We've set a quota of 10 requests per 60 seconds. Let's send more than 10 requests within that window to observe the quota being enforced.
1. Open your terminal.
2. Execute the following command, replacing `<replace-with-key-id>` with the API Key ID you saved earlier. This command attempts to send 15 requests sequentially.
```bash
for i in $(seq 1 15); do \
echo -n "Request $i: "; \
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: <replace-with-key-id>" http://tyk-gateway.localhost:8080/request-quota-test/get; \
sleep 0.1; \
done
```
*(Note: The `sleep 0.1` adds a tiny delay, but ensure all 15 requests execute well within the 60-second quota window).*
3. **Expected Observation:** You should see the first 10 requests succeed, returning an HTTP status code `200`. After the 10th request, the subsequent requests (11 through 15) should be blocked by the quota limit, returning an HTTP status code `403` (Forbidden).
**Sample Output:**
```bash
Request 1: 200
Request 2: 200
Request 3: 200
Request 4: 200
Request 5: 200
Request 6: 200
Request 7: 200
Request 8: 200
Request 9: 200
Request 10: 200
Request 11: 403
Request 12: 403
Request 13: 403
Request 14: 403
Request 15: 403
```
5. **Test Quota Reset:**
Now, let's wait for the quota period (60 seconds) to elapse and then send another request to verify that the quota allowance has been reset.
1. Wait slightly longer than the reset period in the same terminal. The command below waits for 70 seconds.
```bash
echo "Waiting for quota to reset (70 seconds)..."
sleep 70
echo "Wait complete. Sending one more request..."
```
2. Send one more request using the same API key:
```bash
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: <replace-with-key-id>" http://tyk-gateway.localhost:8080/request-quota-test/get
```
3. **Expected Observation:** This request should now succeed, returning an HTTP status code `200`. This demonstrates that because the 60-second quota period ended, the *next* request made after that period triggered the quota reset, replenishing the allowance.
**Sample Output:**
```bash
Waiting for quota to reset (70 seconds)...
Wait complete. Sending one more request...
200
```
This quick start demonstrates the fundamental behaviour of Request Quotas: they limit the total number of requests allowed within a specific period and automatically reset the allowance once that period renews (triggered by the next request).
---
## Configuration Options
Request Quotas in Tyk can be configured at various levels.
The configuration involves setting two specific fields:
1. **QuotaMax**: The maximum number of requests allowed during the quota period.
- Set to `-1` for unlimited requests
- Set to a positive integer (e.g., `1000`) to limit total requests
2. **QuotaRenewalRate**: The time in seconds for which the quota applies.
- Example: `3600` for the hourly quota (1 hour = 3600 seconds)
- Example: `86400` for the daily quota (24 hours = 86400 seconds)
- Example: `2592000` for the monthly quota (30 days = 2592000 seconds)
### System-Level Configuration
Global quota settings are configured in the Tyk Gateway configuration file (`tyk.conf`). These settings affect how quotas are enforced across the entire gateway.
<Tabs>
<Tab title="Config File">
```json
{
// Partial config from tyk.conf
"enforce_org_quotas": true,
"enforce_org_data_detail_logging": false,
"monitor": {
"enable_trigger_monitors": true,
"global_trigger_limit": 80.0,
"monitor_user_keys": true,
"monitor_org_keys": true
},
// ... more config follows
}
enforce_org_quotas: When set to true, enables organization-level quota enforcement
monitor.enable_trigger_monitors: Enables quota monitoring and webhook triggers
monitor.global_trigger_limit: Percentage of quota usage that triggers alerts (e.g., 80.0 means 80%)
monitor.monitor_user_keys: Enables monitoring for individual API keys
monitor.monitor_org_keys: Enables monitoring for organization quotas
{/* Why we are commenting org quotas: Organization quotas are a hangover from the Classic Cloud, where all clients shared a deployment. They are not documented anywhere presently, and I’m not sure why we would start to do so - but if we’re going to, we need to be very careful not to add complexity to the way users configure things. */}
{/* ### Organization-Level Configuration
Organization quotas limit the total number of requests across all APIs for a specific organization. These are enforced by the OrganizationMonitor middleware when enforce_org_quotas is enabled.
quota_max: Maximum number of requests allowed during the quota period
quota_renewal_rate: Time in seconds for the quota period (e.g., 3600 for hourly quotas)
Organization quotas are configured through the Tyk Dashboard API or Gateway API:
curl -X POST -H "Authorization: {your-api-key}" \
-H "Content-Type: application/json" \
-d '{ "quota_max": 1000, "quota_renewal_rate": 3600, }' \
http://tyk-gateway:8080/tyk/org/keys/{org-id}
```*/}### API-Level ConfigurationYou **cannot set** quota values within an API Definition, but you can **disable** quota checking entirely for all requests proxied through that specific API, regardless of Key or Policy settings. This is useful if an API should never have quota limits applied.<Tabs><Tab title="Tyk OAS API Definition">In a Tyk OAS API Definition, you can globally disable quotas for specific APIs:- **skipQuota**: When set to true, disables quota enforcement for the API.- **skipQuotaReset**: When set to true, prevents quota counters from being reset when creating or updating quotas.```json{ // Partial config from Tyk OAS API Definition"middleware": {"global": {"skipQuota": true,"skipQuotaReset": false } }, // ... more config follows}
The Tyk Dashboard provides a straightforward interface to set request quota parameters on Security Policies and Access Keys.
The image below shows a policy with request quotas. Any key using this policy will inherit the quota settings and behave as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
1. Navigate to **API Security > Policies** in the Tyk Dashboard sidebar
2. Click the **Add Policy** button
3. Under the **1. Access Rights** tab and in the **Add API Access Rule** section, select the required API
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* Enable `Request Quotas` by setting the following values in the `Usage Quotas` section:
* Uncheck the `Unlimited Requests` checkbox
* Field **Requests (or connection attempts) per period** - Enter the total number of requests a client can use during the defined quota period.
* Field **Quota resets every:** - Select the duration of the quota period.
5. Select the **2. Configuration** tab
6. In the **Policy Name** field, enter a name
7. From the **Key expire after** dropdown, select an option
8. Click the **Create Policy** button
The image below shows an access key with request quotas. This access key behaves as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
Note: Direct key configuration overrides policy settings only for that specific key.
1. Navigate to **API Security > Keys** in the Tyk Dashboard sidebar
2. Click the **Create Key** button
3. Under the **1. Access Rights** tab:
* Select **Choose API**
* In the **Add API Access Rule** section, select the required API
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* Enable `Request Quotas` by setting the following values in the `Usage Quotas` section:
* Uncheck the `Unlimited Requests` checkbox
* Field **Requests (or connection attempts) per period** - Enter the total number of requests a client can use during the defined quota period.
* Field **Quota resets every:** - Select the duration of the quota period.
5. Select the **2. Configuration** tab
6. In the **Alias** field, enter a name. This human-readable identifier makes tracking and managing this specific access key easier in your analytics and logs.
7. From the **Expires** dropdown, select an option
8. Click the **Create Key** button
Configure via API
These are the fields that you can set directly in the Policy object or the Access Key:
{
// Partial policy/session object fields"quota_max": 1000, // Allow one thousand requests"quota_renewal_rate": 86400, // 1 day or 24 hours// ... more config follows
}
To update the policy, do the following:
Retrieve the policy object using GET /api/portal/policies/{POLICY_ID}
Add or modify the quota_max and quota_renewal_rate fields within the policy JSON object
Update the policy using PUT /api/portal/policies/{POLICY_ID} with the modified object, or create a new one using POST /api/portal/policies/
Explanation:
The above adds request quotas to a policy. Any key using this policy will inherit the quotas settings and behaves as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
Note: Direct key configuration overrides policy settings only for that specific key.
To update the access key do the following:
Retrieve the key's session object using GET /api/keys/{KEY_ID}
Add or modify the quota_max and quota_renewal_rate fields within the session object JSON
Update the key using PUT /api/keys/{KEY_ID} with the modified session object
Explanation:
The above adds quotas to an access key. Any request made by the key will behave as follows: each key will be permitted 1000 requests per 24-hour (86400 seconds) cycle before the quota resets.
Important Considerations
Policy Precedence: Quotas set on a Security Policy apply to all keys using that policy unless overridden by a specific quota set directly on the key (using the "Set per API Limits and Quota" option).
Unlimited Quota: Setting quota_max to -1 grants unlimited requests for the quota period.
Event-Driven Resets: Quotas reset after the quota_renewal_rate (in seconds) has passed and upon the next request using the key. They do not reset automatically on a fixed schedule (e.g., precisely at midnight or the 1st of the month) unless external automation updates the session object.
Response Headers: When quotas are active, Tyk typically adds X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers to responses, allowing clients to track their usage. (Note: Header names might be configurable).
How It Works
Request Quotas in Tyk limit a client's total number of API requests within a defined period (hours, days, months). Unlike rate limits that control the frequency of requests over short intervals (like seconds or minutes) to prevent immediate system overload, Request Quotas control the total volume of requests allowed over much longer periods to manage overall consumption and align with service tiers.
When clients reach their quota limit, further requests are rejected until the quota period renews. It helps API providers implement usage-based pricing tiers, prevent API abuse, control infrastructure costs, and ensure fair resource distribution among clients.
Think of Request Quotas as a prepaid phone plan with a fixed number of minutes per month. When you sign up, you get allocated a specific number of call minutes (API requests) that you can use over the billing period. You can make calls (API requests) at any pace you want – all at once or spread throughout the month – but once you've used up your allocated minutes, you can't make any more calls until the next billing cycle begins.
Tyk implements request quotas using a Redis-based counter mechanism with time-based expiration. Here's a detailed breakdown of the implementation:
graph LR
A[API Request Received] --> B(Check Redis Quota Counter);
B -- Counter < QuotaMax --> C{Increment Redis Counter};
C --> D[Calculate quota_remaining = QuotaMax - Counter];
D --> E[Update Session State];
E --> F[Forward Request to Upstream];
B -- Counter >= QuotaMax --> G[Reject Request with 403];
Loading
Core Components
Redis Storage: Quotas are tracked in Redis using incrementing counters for each API key. The TTL is set to the quota renewal period, and the counter is reset to 0 on the next request after expiration.
Here is a sample Redis key for a Request Quota:
quota-[scope]-[key_hash]
Where:
- scope is optional and represents an API-specific allowance scope
- key_hash is the hashed API key (if hash keys are enabled)
Session State: Quota configuration is stored in the user's SessionState, which contains several quota-related fields:
QuotaMax: Maximum number of requests allowed during the quota period.
QuotaRemaining: Number of requests remaining for the current period. Note: This is a derived value, not the primary counter.
QuotaRenews: Unix timestamp when the quota will reset.
QuotaRenewalRate: Time in seconds for the quota period (e.g., 3600 for hourly quotas).
Middleware: The quota check is performed by the RateLimitAndQuotaCheck middleware
Quota Enforcement
The core logic for checking and enforcing Request Quotas is executed within the RateLimitAndQuotaCheck middleware, which is a step in the request processing pipeline. Here's a breakdown of this process:
Initiation: As a request enters the Tyk Gateway, it passes through configured middleware. The quota validation process begins when it hits the RateLimitAndQuotaCheck middleware.
Applicability Check: The middleware first determines if quota enforcement is relevant:
It checks the API Definition to see if quotas are globally disabled. If so, the process stops here for quotas and the request proceeds.
It identifies the API key for the request and retrieves its associated SessionState.
Retrieve Limits: The middleware accesses the SessionState to get the specific quota parameters applicable to this key and potentially the specific API being accessed (if per-API quotas are configured):
QuotaMax: The maximum number of requests allowed.
QuotaRenewalRate: The duration (in seconds) of the quota period for setting the TTL in Redis.
Redis Interaction & Enforcement: This is the core enforcement step, interacting directly with Redis:
Construct Key: Generates the unique Redis key for tracking this specific quota counter (e.g., quota-{scope}-{api-key-hash}).
Check Expiry/Existence: It checks Redis to see if the key exists and if its TTL is still valid.
Handle Renewal (If Expired/Missing): If the key doesn't exist or its TTL has passed, Tyk initiates the renewal logic described previously (attempting a distributed lock, setting the counter to 0, and applying the QuotaRenewalRate as the new TTL).
Increment Counter: Tyk atomically increments the Redis counter value. This operation returns the new value of the counter after the increment.
Compare Against Limit: The middleware compares this new counter value against the QuotaMax retrieved from the session state.
Decision:
If new_counter_value <= QuotaMax: The request is within the allowed quota.
If new_counter_value > QuotaMax: This request has exceeded the quota limit.
Outcome:
Quota OK: The middleware allows the request to proceed to the next stage in the processing pipeline (e.g., other middleware, upstream service).
Quota Exceeded: The middleware halts further request processing down the standard pipeline. It prepares and returns an error response to the client, typically HTTP 403 Forbidden with a "Quota exceeded" message.
Session State Update: Regardless of whether the request was allowed or blocked due to the quota, the middleware calls an internal function (like updateSessionQuota) to update the in-memory SessionState associated with the API key. This update synchronizes the QuotaRemaining field in the session with the latest calculated state based on the Redis counter and its expiry. It ensures that subsequent operations within the same request lifecycle (if any) or diagnostic information have access to the most recent quota status.
Quota Reset Mechanisms
The available allowance (QuotaRemaining) for an API key is replenished back to its maximum (QuotaMax) through several distinct mechanisms:
Event-Driven Renewal (Primary Mechanism):
Condition: This occurs after the time duration specified by QuotaRenewalRate (in seconds) has elapsed since the quota period began (i.e., since the last reset or key creation/update). In Redis, this corresponds to the Time-To-Live (TTL) expiring on the quota tracking key.
Trigger: The reset is not automatic based on a timer. It is triggered by the next API request made using that specific key after the QuotaRenewalRate duration has passed (and the Redis TTL has expired).
Process: Upon detecting the expired TTL during that next request, Tyk resets the Redis counter (typically by setting it to 0 and immediately incrementing it to 1 for the current request) and applies a new TTL based on the QuotaRenewalRate. This effectively makes the full QuotaMax available for the new period starting from that moment.
graph LR
A[Request After Quota Period] --> B{Redis Key Expired?};
B -- Yes --> C[Reset Counter to 0];
C --> D[Set New Expiration];
D --> E[Process Request Normally];
B -- No --> F[Continue Normal Processing];
Loading
Manual Reset via API:
Mechanism: You can force an immediate quota reset for a specific API key by calling an endpoint on the Tyk Gateway Admin API.
Effect: This action directly deletes the corresponding quota tracking key in Redis. The next request using this API key will find no existing key, triggering the renewal logic (Step 1) as if the period had just expired, immediately granting the full QuotaMax and setting a new TTL. This provides an immediate, on-demand refresh of the quota allowance.
Key Creation or Update:
Trigger: When a new API key is created or an existing key's configuration is updated (e.g., via the Dashboard or the Gateway API), Tyk reapplies the quota settings based on the current policy or key-specific configuration.
Process: This typically involves setting the QuotaRemaining value to QuotaMax in the key's session data and ensuring the corresponding Redis key is created with the correct initial value (or implicitly reset) and its TTL set according to the QuotaRenewalRate. This ensures the key starts with a fresh quota allowance according to its defined limits.
Exception: This behavior can be suppressed if the API definition includes the DontSetQuotasOnCreate field (referred to as SkipQuotaReset in the OAS specification), which prevents automatic quota resets during key creation or updates.
Key Technical Aspects
Time-Based Reset: Unlike rate limiting, which uses sliding windows, quotas have a fixed renewal time determined by QuotaRenewalRate (in seconds)
</details>
<details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/1098/files#diff-58a536d25b2b7189628d843380371c1b263909af63606716da471ea511eb60deR133-R141'><strong>UI Label Fidelity</strong></a>
Confirm that UI labels referenced (e.g., “Disable rate limiting”, “Global Limits and Quota”, “Max Requests per period”, “Quota resets every”) match the current Dashboard wording to avoid user confusion.
</summary>
```txt
1. Navigate to **API Security > Policies** in the Tyk Dashboard sidebar.
2. Click the **Add Policy** button.
3. Under the **1. Access Rights** tab, in the **Add API Access Rule** section, select the `Request Quota Test` API.
4. Scroll down to the **Global Limits and Quota** section (still under the **1. Access Rights** tab):
* **Important:** Disable **[Rate Limiting](/api-management/rate-limit)** by selecting **Disable rate limiting** option, so it doesn't interfere with testing the quota.
* Set the following values for `Usage Quotas`:
* Uncheck the `Unlimited requests` checkbox
* Enter `10` into the **Max Requests per period** field. (This is our low quota limit for testing).
* Select `1 hour` from the **Quota resets every:** dropdown. (In the next step, we will modify it to 60 seconds via API for quick testing, as 1 hour is a very long period. From the dashboard, we can only select pre-configured options.)
The link targets a cluster/sentinel reference, which may be misleading for standard single-node Redis setups. Link to a general Redis configuration page to avoid misguiding users and ensure broader applicability.
-Tyk implements request quotas using a [Redis](/tyk-configuration-reference/redis-cluster-sentinel)-based counter mechanism with time-based expiration.+Tyk implements request quotas using a [Redis](/tyk-configuration-reference/redis)‑based counter mechanism with time-based expiration.
Suggestion importance[1-10]: 6
__
Why: Suggestion is accurate to the new text and improves clarity by referencing more general docs, reducing potential confusion for non-cluster users. It’s a minor but useful docs correctness improvement.
Low
Use general Redis reference
Consistently linking to the cluster/sentinel page can confuse readers who do not use those modes. Use the general Redis configuration reference for accuracy and consistency with diverse deployments.
-1. **[Redis](/tyk-configuration-reference/redis-cluster-sentinel) Storage**: Quotas are tracked in Redis using incrementing counters for each API key. The TTL is set to the quota renewal period, and the counter is reset to 0 on the next request after expiration.+1. **[Redis](/tyk-configuration-reference/redis) Storage**: Quotas are tracked in Redis using incrementing counters for each API key. The TTL is set to the quota renewal period, and the counter is reset to 0 on the next request after expiration.
Suggestion importance[1-10]: 6
__
Why: Consistent with suggestion 2; updating to the general Redis config page improves applicability and avoids misleading readers. It’s correct and helpful but not critical.
Low
Possible issue
Fix potentially broken deep link
The anchor #access-key might not exist on the referenced page, causing a broken link. Update the link to point to the canonical Access Keys documentation path or use a verified anchor within the policies page.
-The Tyk Dashboard provides a straightforward interface to set request quota parameters on [Security Policies](/api-management/policies) and [Access Keys](/api-management/policies#access-key).+The Tyk Dashboard provides a straightforward interface to set request quota parameters on [Security Policies](/api-management/policies) and [Access Keys](/api-management/access-keys).
Suggestion importance[1-10]: 5
__
Why: Reasonable catch that the anchor #access-key might be invalid; however, it’s speculative and not verifiable from the diff. Impact is moderate as it prevents a possible broken link but isn’t critical.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
Summary
This PR improves the documentation navigation on the Request Quotas page by adding cross-reference links to related concepts and features:
/api-management/rate-limitwherever rate limiting is mentioned in context of how it differs from quotas/api-management/policiesfor policy-related concepts/api-management/policies#access-keyfor access key documentation/tyk-configuration-reference/redis-cluster-sentinelin the technical implementation sectionsChanges
The following types of cross-references were added:
Test plan
🤖 Generated with Claude Code
PR Type
Documentation
Description
Add internal cross-reference links
Link policies, rate limits, Redis, keys
Improve UI instructions clarity
Enhance conceptual comparisons
Diagram Walkthrough
File Walkthrough
request-quotas.mdx
Add cross-references throughout Request Quotas docapi-management/request-quotas.mdx
/api-management/policies/api-management/rate-limit