> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-worktree-docs-descriptions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Upstash Ratelimit Strapi Plugin

> Configure the Upstash Ratelimit Strapi plugin with rate limit algorithms, tokens, windows, identifier sources, and per-route strategies.

After setting up the plugin, it's possible to customize the ratelimiter algorithm and rates. You can also define different rate limits and rate limit algorithms for different routes.

## General Configurations

<ParamField path="enabled" type="boolean" default="true">
  Enable or disable the plugin.
</ParamField>

## Database Configurations

<ParamField path="token" type="string" required>
  The token to authenticate with the Upstash Redis REST API. You can find this
  credential on Upstash Console with the name `UPSTASH_REDIS_REST_TOKEN`
</ParamField>

<ParamField path="url" type="string" required>
  The URL for the Upstash Redis REST API. You can find this credential on
  Upstash Console with the name `UPSTASH_REDIS_REST_URL`
</ParamField>

<ParamField path="prefix" type="string" default="@strapi">
  The prefix for the rate limit keys. The plugin uses this prefix to store the
  rate limit data in Redis. <br />
  For example, if the prefix is `@strapi`, the key will be
  `@strapi:<method>:<route>:<identifier>`.
</ParamField>

<ParamField path="analytics" type="boolean" default="false">
  Enable analytics for the rate limit. When enabled, the plugin extra insights
  related to your ratelimits. You can use this data to analyze the rate limit
  usage on [Upstash Console](https://console.upstash.com/ratelimit).
</ParamField>

## Strategy

The plugin uses a strategy array to define the rate limits per route. Each strategy object has the following properties:

<ParamField path="methods" type="('GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH' |'ALL')[]" required>
  An array of HTTP methods to apply the rate limit. <br />
  For example, `["GET", "POST"]`
</ParamField>

<ParamField path="path" type="string" required>
  The path to apply the rate limit. You can use wildcards to match multiple
  routes. For example, `*` matches all routes. <br />
  Some examples: <br />

  * `path: "/api/restaurants/:id"` <br />
  * `path: "/api/restaurants"` <br />
</ParamField>

<ParamField path="identifierSource" type="string" required>
  The source to identifiy the user. Requests with the same identifier will be
  rate limited under the same limit. <br />
  Available sources are: <br />

  * `ip`: The IP address of the user. <br />
  * `header`: The value of a header key. You should pass the source in the `header.<HEADER_KEY>` format. <br />
    For example, `header.Authorization` will use the value of the `Authorization`
</ParamField>

<ParamField path="debug" type="string">
  Enable debug mode for the route. When enabled, the plugin logs the remaining
  limits and the block status for each request. <br />
</ParamField>

<ParamField path="limiter" type="object" required>
  The limiter configuration for the route. The limiter object has the following
  properties:

  <Card>
    <ParamField path="algorithm" type="'fixed-window' | 'sliding-window' | 'token-bucket'" required>
      The rate limit algorithm to use. For more information related to algorithms, see docs [**here**](/redis/sdks/ratelimit-ts/algorithms). <br />

      * `fixed-window`: The fixed-window algorithm divides time into fixed intervals. Each interval has a set limit of allowed requests. When a new interval starts, the count resets. <br />
      * `sliding-window`:
        The sliding-window algorithm uses a rolling time frame. It considers requests from the past X time units, continuously moving forward. This provides a smoother distribution of requests over time. <br />
      * `token-bucket`: The token-bucket algorithm uses a bucket that fills with tokens at a steady rate. Each request consumes a token. If the bucket is empty, requests are denied. This allows for bursts of traffic while maintaining a long-term rate limit.<br />
    </ParamField>

    <ParamField path="tokens" type="number" required>
      The number of tokens allowed in the time window. <br />
    </ParamField>

    <ParamField path="window" type="string" required>
      The time window for the rate limit. Available units are `"ms" | "s" | "m" | "h" | "d"` <br />
      For example, `20s` means 20 seconds.
    </ParamField>

    <ParamField path="refillRate" type="number">
      The rate at which the bucket refills. **This property is only used for the token-bucket algorithm.** <br />
    </ParamField>
  </Card>
</ParamField>

## Examples

<CodeGroup>
  ```json Apply rate limit for all routes theme={"system"}
  {
     "strapi-plugin-upstash-ratelimit":{
        "enabled":true,
        "resolve":"./src/plugins/strapi-plugin-upstash-ratelimit",
        "config":{
           "enabled":true,
           "token":"process.env.UPSTASH_REDIS_REST_TOKEN",
           "url":"process.env.UPSTASH_REDIS_REST_URL",
           "strategy":[
              {
                 "methods":[
                    "GET",
                    "POST"
                 ],
                 "path":"*",
                 "identifierSource":"header.Authorization",
                 "limiter":{
                    "algorithm":"fixed-window",
                    "tokens":10,
                    "window":"20s"
                 }
              }
           ],
           "prefix":"@strapi"
        }
     }
  }
  ```

  ```json Apply rate limit with IP theme={"system"}
  {
    "strapi-plugin-upstash-ratelimit": {
      "enabled": true,
      "resolve": "./src/plugins/strapi-plugin-upstash-ratelimit",
      "config": {
        "enabled": true,
        "token": "process.env.UPSTASH_REDIS_REST_TOKEN",
        "url": "process.env.UPSTASH_REDIS_REST_URL",
        "strategy": [
          {
            "methods": ["GET", "POST"],
            "path": "*",
            "identifierSource": "ip",
            "limiter": {
              "algorithm": "fixed-window",
              "tokens": 10,
              "window": "20s"
            }
          }
        ],
        "prefix": "@strapi"
      }
    }
  }
  ```

  ```json Routes with different rate limit algorithms theme={"system"}
  {
    "strapi-plugin-upstash-ratelimit": {
      "enabled": true,
      "resolve": "./src/plugins/strapi-plugin-upstash-ratelimit",
      "config": {
        "enabled": true,
        "token": "process.env.UPSTASH_REDIS_REST_TOKEN",
        "url": "process.env.UPSTASH_REDIS_REST_URL",
        "strategy": [
          {
            "methods": ["GET", "POST"],
            "path": "/api/restaurants/:id",
            "identifierSource": "header.x-author",
            "limiter": {
              "algorithm": "fixed-window",
              "tokens": 10,
              "window": "20s"
            }
          },
          {
            "methods": ["GET"],
            "path": "/api/restaurants",
            "identifierSource": "header.x-author",
            "limiter": {
              "algorithm": "tokenBucket",
              "tokens": 10,
              "window": "20s",
              "refillRate": 1
            }
          }
        ],
        "prefix": "@strapi"
      }
    }
  }
  ```
</CodeGroup>