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

# Configure Upstash Ratelimit Strapi Plugin

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>