API shielding rule

How to block direct requests to selected API endpoints that bypass your website.

Available only in Anti-bot mode.

This feature is enabled on request. If the Enforcement tab in Custom rules is inactive in the UI, contact support to enable it.

You can create only one API shielding rule for each resource.

About the rule

Description

An API shielding rule lets you specify the endpoints for which protection blocks direct requests that bypass your website.

It is suitable for endpoints that:

  • are used by the frontend;

  • are not intended for direct calls through curl, scripts, or other external tools;

  • are not a public API for external clients and integrations.

Example: your online store uses the /api/cart API to add products to a cart. When a user clicks Add to cart on a page, the browser sends a request to this API. If someone tries to call /api/cart directly without first using the website, protection blocks the request.

How it works

  1. The user opens a browser and sends a request to your website.

  2. The request passes through protection. If it is legitimate, protection forwards it to your server.

  3. The server sends a response.

  4. The response passes through protection. Protection adds a Strictera service cookie to the response.

  5. The browser receives the response and saves the cookie. The cookie is included in all subsequent requests to your website.

  6. When the user requests a URI path that you have added to the API shielding rule, protection checks the Strictera service cookie in the request:

    • If the required cookie is missing, protection blocks the request.

    • If the required cookie is present, protection first checks that it is not forged. It then calculates how long ago the user last visited the website. If the allowed access time has expired, protection blocks the request. If it has not expired, protection checks the request against other filtering policies and forwards it to your server if it is legitimate.

How it differs from enforcement rules

An API shielding rule is a special rule type in the Custom rules section. It is created alongside enforcement rules, but its operation, settings, and evaluation order are different.

API shielding rule Enforcement rule

When to choose it

You need to protect internal API paths that must be called only while a user is working with the website.

You need to filter requests by conditions and apply selected actions to them.

What you can configure

The URL path and access time: the period after the user’s last website visit during which the user can access the path.

Conditions:

  • traffic parameters: URI path, country, ASN, query string, headers, cookies, request method, User-Agent, IP address, subnet, SP hash, and others;

  • rate limits: global and per-IP;

  • whether the rule applies based on DDoS status.

The action for a request that matches the rule conditions:

  • pass;

  • block;

  • return a JavaScript challenge;

  • return a cookie challenge;

  • return a CAPTCHA.

You can select a separate action for every source class: Human, Likely human, Likely bot, and Bot.

What happens to a request

The request is passed if it contains a valid Strictera service cookie and the allowed access time has not expired. In all other cases, the request is blocked.

If a request matches the conditions, the configured action is applied: pass, block, return a JavaScript challenge, return a cookie challenge, or return a CAPTCHA.

How many rules you can create

One rule, but you can add multiple API paths to it.

20 rules. Contact support if you need a higher limit.

How it appears in the UI

The first rule in the list, without a number.

Below the API shielding rule, with a number in the general list.

Place in the filtering hierarchy

Protection filters every request in stages: first with one filtering mechanism, then another, and so on. The list below shows where the API shielding rule is placed:

If a request matches the conditions of several filtering mechanisms, the one that is evaluated first applies. For example, the white list is evaluated before the API shielding rule. Therefore, a request from an IP address on the white list is passed to the resource even if it targets an endpoint for which an API shielding rule is configured.

Recommendations

  • Add only URL paths that are called while a user is working with the website and must not be called directly.

  • An API shielding rule is not suitable for a public API that mobile apps, external clients, or integrations must call directly. To protect such an API, contact support. We will analyze its traffic, perform legitimate traffic learning, and configure filtering.

  • You can create only one API shielding rule for each resource. If you need to protect several API paths, add them to one rule with the + Or button.

  • Do not use the rule instead of authorization. It protects the API from direct requests that bypass the website, but does not check the user’s permissions within your resource.

  • Choose the access time based on user behavior and your resource’s usage scenarios. If a user can interact with the resource for a long time after opening a page, set a longer period, such as eight or 24 hours. If the API is called only immediately after the website is opened, use a shorter period, such as 30 minutes or one hour.

Configuration

Open Enforcement

Go to Application protection → Resources. For the resource where you want to configure a rule, click the ellipsis (…) and select Custom rules. The page that opens contains the Enforcement tab.

Create an API shielding rule

Before creating the rule, make sure that the Strictera service cookie can be passed between the website and the API. This is critical: otherwise, the rule blocks all requests to the specified URI paths because they do not contain the required cookie.

If your website and API are located:

  • On the same domain, for example, example.com and example.com/api, configure cookie transfer on your side as described below.

  • On different subdomains of the same domain, for example, site.example.com and api.example.com, do the following:

    1. Contact support so that we can configure cookie transfer on our side.

    2. Configure cookie transfer on your side as described below.

  • On different domains, for example, example.com and api.example.net, passing the service cookie between the resources is not possible. You cannot configure an API shielding rule.

Instructions for configuring cookie transfer

1. Configure CORS on the API side.

Open the site.conf configuration file that processes the domain, and add the following headers.

The required headers depend on your API configuration. You may need to add them only for certain locations of the resource.

Header Value Example

Access-Control-Allow-Origin

The specific website domain. Do not use *, otherwise the browser will not send cookies.

add_header 'Access-Control-Allow-Origin' 'https://site.example.com' always;

Access-Control-Allow-Credentials

true, to allow cookies to be passed in requests.

add_header 'Access-Control-Allow-Credentials' 'true' always;

Access-Control-Allow-Methods

The API methods in use. Optional.

add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';

Access-Control-Allow-Headers

The API headers in use. Optional.

add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, X-API-Key, X-CSRF-Token';

2. Enable cookie transfer on the website side.

Find the JavaScript code that sends requests to the API and add credentials transfer.

These settings let the browser receive the service cookie after it passes additional checks on the website side and include it in subsequent requests to the API.

For Fetch:

fetch('https://api.example.com', {
  method: 'GET',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
  },
});

For XMLHttpRequest:

const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.example.com', true);
xhr.withCredentials = true;
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.send();
  1. Click + Create enforcement rule and select API shielding rule. The rule creation window opens. Complete the remaining steps there.

    If clicking + Create enforcement rule does not open a drop-down menu, you already have an API shielding rule. You cannot create a second one, but you can edit the first rule and add new URI paths to it.

  2. Specify the Protected URL paths.

    First, choose a comparison operator:

    • = (equals)—the rule applies only to the specified path. For example, with = /api/search, protection checks only requests to /api/search.

    • *... (starts with)—the rule applies to the specified path and all nested paths. For example, with *... /api/cart, protection checks requests to /api/cart, /api/cart/add, /api/cart/remove, and other paths with this prefix.

    Then specify the path. It must begin with /.

    To add several URL paths at once, use the + Or button. The rule protects requests to any of these paths.

    Example values:

    /api/search

    /api/items OR /api/cart

  3. Configure the Allowed API access time after last website visit.

    When a request to any URI path specified in step 2 arrives, protection checks how long ago the user last visited the website. If the allowed API access time has expired, protection blocks the request.

    You can select a preset value from the list or set a custom time in minutes. The maximum value is 1,440 minutes, or 24 hours.

  4. Click Create.

    The new rule appears in the list on the Enforcement tab. It is always at the top and has no number in the No. column.

    To activate the rule, turn on the switch in the Enabled column.

    Switch for enabling and disabling a rule

Configuration example

Task: protect the search API and product card API from direct calls that bypass the website.

Rule settings:

  • Protected URL paths—*... /api/search OR *... /api/item.

  • Allowed API access time after last website visit—8 hours.

For eight hours after the last visit to your website, a user can access /api/search, /api/item, and their nested paths if all three conditions are met:

  • The request is made from the same browser that was used to visit the website.

  • The user has not cleared cookies for your website during those eight hours.

  • The user does not make the request in incognito mode.

Management

In Custom rules → Enforcement, you can manage the rule directly in the list:

  • Enable or disable: use the switch in the Enabled column to temporarily enable or disable the rule.

  • Edit: click the ellipsis (…) at the end of the row and select Edit. You can change any rule parameter there.

  • Delete: click the ellipsis (…), select Delete, and confirm the action. After you delete the rule, you can select API shielding rule in the creation menu again.

Actions for the rule