Rate limit configuration

Each Arcjet rate limit rule has its own configuration depending on the algorithm used.

Characteristics

Type: Array<string> (optional)

Algorithms: fixedWindow, slidingWindow, tokenBucket.

Defines how Arcjet will track the rate limit.

If this is not set then the characteristics set on the root Arcjet object will be used.

Note

For most use cases it is better to use the global characteristics set on the root Arcjet object. This is because we cache rate limit decisions using a fingerprint that is generated with these characteristics. If the characteristics used to compute the fingerprint are different from those used to apply the rate limit it can result in cached rate limit decisions being applied to the wrong set of users.

Built-in characteristics

The built-in options are managed by the SDK and are always available. If more than one option is provided, they will be combined.

Caution

If you specify different characteristics and do not include ip.src, you may inadvertently rate limit everyone. Be sure to include a characteristic which can narrowly identify each client. For example, use a header value to limit based on a session token or authentication header.

Option	Description
ip.src	Client IP address
http.host	Request host
http.request.headers["<header_name>"]	Request header value
http.request.cookie["<cookie_name>"]	Request cookie value
http.request.uri.args["<query_param_name>"]	Request query value
http.request.uri.path	Request path

Custom characteristics

You can use custom characteristics to track rate limits. For example, you can set up a limit for a logged in user by setting their user ID as the identifier. This will apply the limit to all requests made by that user regardless of their device and IP address.

Custom characteristics are defined with a string key when configuring the rate limit rule. The value is then passed as a string, number or boolean when calling the protect method. You can use any string value for the key.

Caution

Avoid passing personal information such as an email address as a custom characteristic. The value is hashed on Arcjet’s servers, but it’s still a best practice to avoid sending us sensitive information.

User ID

In this example we create a custom characteristic called userId, but you can call it anything you like:

import arcjet, { fixedWindow } from "@arcjet/next";

const aj = arcjet({
  key: process.env.ARCJET_KEY!,
  characteristics: ["userId"], // track requests by a custom user ID
  rules: [
    fixedWindow({
      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
      window: "60s", // 60 second fixed window
      max: 100, // allow a maximum of 100 requests
    }),
  ],
});

Then when calling the protect method, you would pass a value for the key:

// Pass userId as a string to identify the user. This can be any string,
// number or boolean value. Multiple values will be combined.
const decision = await aj.protect(req, { userId: "user123" });

IP address + User ID

If you want to be more flexible and use the user IP address for anonymous users and a user ID for logged in users, you can create a custom fingerprint characteristic that is defined separately:

import arcjet, { fixedWindow } from "@arcjet/next";

const aj = arcjet({
  key: process.env.ARCJET_KEY!,
  characteristics: ["fingerprint"], // track requests by a custom fingerprint
  rules: [
    fixedWindow({
      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
      window: "60s", // 60 second fixed window
      max: 100, // allow a maximum of 100 requests
    }),
  ],
});

Then when calling the protect method, you would pass a value for the key:

if (userIsLoggedIn) {
  // Set fingerprint to the user ID from the session or database
  const fingerprint = "userId";
  const decision = await aj.protect(req, { fingerprint });
} else {
  // In Next.js, you can use `req.ip` to get the user's IP address. Other
  // frameworks may have different methods.
  const fingerprint = req.ip;
  const decision = await aj.protect(req, { fingerprint });
}

Max

Type: int (required)

Algorithms: fixedWindow, slidingWindow.

The maximum number of requests allowed in the time window. This is an integer value ranging from 0 to 4,294,967,295.

Window

Type: string | int (required)

Algorithms: fixedWindow.

The time window the rate limit applies to. Can be an int specifying the window size in seconds ranging from 0 to 4,294,967,295. Alternatively, you can use a string with a sequence of numbers, each with a unit suffix e.g. 1s for 1 second, 1h45m for 1 hour and 45 minutes, 1d for 1 day.

Valid string time units are:

• s for seconds.
• m for minutes.
• h for hours.
• d for days.

Interval

Type: string | int (required)

Algorithms: slidingWindow, tokenBucket.

For slidingWindow, the time interval for the rate limit. For example, if you set the interval to 60 the sliding window will be 60 seconds.

For tokenBucket, the time interval for the refill rate (see below). For example, if you set the interval to 60 and the refill rate to 10, the bucket will refill 10 tokens every 60 seconds.

In both cases, the value can be an int in seconds ranging from 0 to 4,294,967,295. Alternatively, you can use a string with a sequence of numbers, each with a unit suffix e.g. 1s for 1 second, 1h45m for 1 hour and 45 minutes, 1d for 1 day.

Valid string time units are:

• s for seconds.
• m for minutes.
• h for hours.
• d for days.

Refill rate

Type: int (required)

Algorithms: tokenBucket.

The number of tokens to add to the bucket at each interval (see above). This is an integer value ranging from 0 to 4,294,967,295. For example, if you set the interval to 60 and the refill rate to 10, the bucket will refill 10 tokens every 60 seconds.

Capacity

Type: int (required)

Algorithms: tokenBucket.

The maximum number of tokens the bucket can hold. The bucket will refill until it hits the capacity. This is an integer value ranging from 0 to 4,294,967,295.

Discussion