Skip to content

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.

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.

OptionDescription
ip.srcClient IP address
http.hostRequest 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.pathRequest 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.

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