Configuring rate limiting

The previous version of rate-limiting rules is now deprecated. The rate-limiting rules interface for the previous version will remain available until 30 July 2025. After this date, any active rules from the previous version will no longer function.

Rate limiting (Enterprise plan only) protects against denial-of-service attacks, brute-force login attempts, and other types of abusive behavior targeting the application layer.

Select the type of rate-limiting rule, either a Custom rule or Protect login.

Creating a custom rate-limiting rule

Creating a custom rate-limiting rule in the UI

Enter a rule name that helps you remember what the rule does. This is an optional field.

In the Traffic matching criteria section, enter the following information.

Select the criteria type.
Enter the URL that you are rate limiting.
Select the number of requests to allow before triggering rate limiting.
Select the time period (in seconds) over which the requests can occur before triggering rate limiting.

The range is from 10 to 86,400 seconds.

The Advanced Criteria option allows you to specify which HTTP methods, header responses, and origin response codes to further restrict the matching criteria.

Select a value form the Method list menu (ANY is the default).

Update the HTTP response header. You can also Add response header to include headers returned by your origin web server.

If you have more than one header under the HTTP response header, an AND Boolean logic applies. To exclude a header from being matched, use the Not Equal option. Also, each header must be an exact match. However, case sensitivity doesn't apply.

Under Origin response code, type the valid numerical value of each HTTP response code to match. To include two or more response codes, separate each value with a comma. For example, you can enter 401, 403 if you only want those two error codes to count.

Configuring the response

Select from the actions listed, and specify the timeout period. In this case, the timeout refers to the ban period that the action takes place. A 60-second timeout means that the action is applied for 60 seconds.

Actions for rate limiting
Action	Description
Block	Issues a 429 error when the threshold is exceeded
Challenge	User must pass a Google reCaptcha Challenge before proceeding. If successful, the request is accepted. Otherwise, the request gets blocked.
JS Challenge	The user must pass a Javascript Challenge before proceeding. If successful, the request is accepted. Otherwise, the request gets blocked.
Simulate	You can use this option to test your rule before applying any of the other options in your live environment.

In the Advanced response section, specify the response type when a rule's threshold is exceeded.

Bypassing URLs

Bypass lets you create the equivalent of an allowlist or exception for a set of URLs. No actions trigger for those URLs, even if the rate-limiting rule is matched.

Creating a custom rate-limiting rule with the API

Getting the rate-limiting rule entry point for the API

All rate-limiting rule API operations require a RULESET_ID of the entry point ruleset for the rate-limiting rules phase. This entry point ruleset may already exist or needs to be created if it does not exist.

Follow these steps to get the rate-limiting rule entry point ruleset:

Set up your API environment with the correct variables.
Store the following values in variables to be used in the API command:

CRN: The full URL-encoded Cloud Resource Name (CRN) of the service instance.

ZONE_ID: The domain ID.

When all variables are initiated, get the entry point ruleset:

curl -X GET "https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets/phases/http_ratelimit/entrypoint" \
--header "X-Auth-User-Token: Bearer <API_TOKEN>" \
--header "Content-Type: application/json"

The ruleset ID will be in the response of the successful request. If the above call returns a 404 Not Found response, use the following API to create the entrypoint ruleset for the rate-limiting rule phase:

curl -x POST https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets \
--header "X-Auth-User-Token: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "Zone-level phase entry point",
  "kind": "zone",
  "description": "Rate-limting rule entry point ruleset.",
  "phase": "http_ratelimit"
}'

Creating a rate-limiting rule with the API

Follow these steps to create a rate-limiting rule with the API:

Set up your API environment with the correct variables.
Store the following values in variables to be used in the API command:

CRN: The full URL-encoded Cloud Resource Name (CRN) of the service instance.

ZONE_ID: The domain ID.

RULESET_ID: The ID of the rate-limiting rule entrypoint ruleset.

When all variables are initiated, create the rate-limiting rule:

curl -X POST "https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets/$RULESET_ID/rules" \
--header "X-Auth-User-Token: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My rate limiting rule",
  "expression": "(http.request.uri.path matches \"^/api/\")",
  "action": "block",
  "ratelimit": {
    "characteristics": [
      "cf.colo.id",
      "ip.src"
    ],
    "period": 60,
    "requests_per_period": 100,
    "mitigation_timeout": 600
  }
}'

Updating a rate-limiting rule with the API

Follow these steps to update an existing rate-limiting rule with the API:

Set up your API environment with the correct variables.
Store the following values in variables to be used in the API command:

CRN: The full URL-encoded Cloud Resource Name (CRN) of the service instance.

ZONE_ID: The domain ID.

RULESET_ID: The ID of the rate-limiting rule entrypoint ruleset.

RULE_ID: The ID of the rate-limiting rule to be modified.

When all variables are initiated, update the rate-limiting rule:

curl -X PATCH "https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets/$RULESET_ID/rules/$RULE_ID" \
--header "X-Auth-User-Token: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "enabled": true,
  "description": "rate limit IPs for API"
}'

Deleting a rate-limiting rule with the API

Follow these steps to delete an existing rate-limiting rule with the API:

Set up your API environment with the correct variables.
Store the following values in variables to be used in the API command:

CRN: The full URL-encoded Cloud Resource Name (CRN) of the service instance.

ZONE_ID: The domain ID.

RULESET_ID: The ID of the rate-limiting rule entrypoint ruleset.

RULE_ID: The ID of the rate-limiting rule to be modified.

When all variables are initiated, delete the rate-limiting rule:

curl -X DELETE "https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets/$RULESET_ID/rules/$RULE_ID" \
--header "X-Auth-User-Token: Bearer <API_TOKEN>" \
--header "Content-Type: application/json"

MISSING - DO ANY OF THE SECTIONS IN THE UI SECTION APPLY HERE?