Request Quotas

Introduction

Request Quotas in Tyk Gateway allow you to set a maximum number of API requests for a specific API key or Policy over longer, defined periods (e.g., day, week, month). This feature is distinct from rate limiting (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.

    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

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.

      Click to expand API Definition

      {
        "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/"
          }
        }
      }
      

Configure Policy and Quota

2. Create and Configure a Security Policy with a Request Quota:

   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 by selecting Disable rate limiting option, so it doesn’t interfere with testing the quota.
      • Set the following values for Usage Quotas:
      • Enter 10 into the Max Requests per period field. (This is our low quota limit for testing).
      • TODO: 60 seconds cannot be selected.
      • Select Custom from the Quota resets every: dropdown and enter 60 in the adjacent field. (This sets a short 60-second reset period for quick testing).
   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.

   TODO: Add Image (Note: Replace with an actual screenshot showing the Quota fields configured as described)

3. Associate an Access Key with the Policy:

   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.

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.

   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:

   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.

      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:

      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:

   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 is configured within Tyk Security Policies or directly on individual Access Keys.

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.

{
// 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
}

export TYK_GW_ENFORCEORGQUOTAS=true

Refer to the Tyk Gateway Configuration Reference for more details on this setting.

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 Configuration

You 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.

{
  // Partial config from Tyk OAS API Definition
  "middleware": {
    "global": {
      "skipQuota": true,
      "skipQuotaReset": false
    }
  },
  // ... more config follows
}

{
  // Partial config from Tyk Classic API Definition
  "disable_quota": true // Set to true to disable quota checks
  // ... more config follows
}

Configure via UI

The Tyk Dashboard provides a straightforward interface to set request quota parameters on Security Policies and Access Keys.

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
}

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.

    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
  

How Tyk Implements Quotas

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];
  

Core Components

1. 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)

2. 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).

3. 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:

1. Initiation: As a request enters the Tyk Gateway, it passes through configured middleware. The quota validation process begins when it hits the RateLimitAndQuotaCheck middleware.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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:

1. 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];
     

2. 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.

3. 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

1. Time-Based Reset: Unlike rate limiting, which uses sliding windows, quotas have a fixed renewal time determined by QuotaRenewalRate (in seconds)

2. Atomic Operations: Redis pipelining is used to ensure atomic increment and expiration setting:

3. Race Condition Handling: Distributed locks prevent multiple servers from simultaneously resetting quotas

4. Quota Scope Support: The implementation supports both global quotas and API-specific quotas through the scoping mechanism

FAQs

POST /tyk/keys/reset/{key_id}
Authorization: {your-gateway-secret}