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.
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.
User ID
In this example we create a custom characteristic called userId
, but you can call it anything you like:
Then when calling the protect
method, you would pass a value for the key:
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:
Then when calling the protect
method, you would pass a value for the key:
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
.