Skip to content

Configure bot detection

Shield's Bot Detection spots automated traffic — scrapers, credential stuffers, and other non-human clients — and either logs it or challenges it before it reaches your site. It scores each visitor using several signals (request integrity, IP reputation, and browser fingerprinting) and you control how sensitive each signal is. This guide covers turning it on and tuning it from the site dashboard.

Bot Detection is a premium Shield feature

Unlike the WAF, Bot Detection is only available on the premium Shield tier. On a plan with the base Shield tier, the Bot Detection page shows a "Bot Detection requires a higher plan" card with an Upgrade plan button instead of the settings form.

Before you start

  • A site with Shield included in its plan, on the premium tier. If Shield isn't part of your plan at all, every Shield page shows a "Shield isn't included in your plan" card. If it's included but only on the base tier, the Bot Detection page shows an upgrade card.
  • Shield must be activated for the site. If it hasn't been, the page shows a "Shield isn't active for this site" message with an Activate Shield button — activate it first.

Open the Bot Detection page

  1. Open your site, then in the left sidebar choose Shield.

  2. Select the Bot Detection tab. Shield's sub-navigation runs across the top: Overview, WAF, Bot Detection, Rate Limits, Access Lists, and Security Events. Choose Bot Detection.

The page loads the current settings live and shows a Bot Detection Settings card.

Choose an execution mode

At the top of the card, Execution Mode is a two-option control:

  • Log only — records bot detections without blocking anything.
  • Challenge — presents suspected bots with a browser verification challenge.

Tip

Start in Log only, watch the Security Events log to see what would be challenged, then switch to Challenge once you're confident legitimate visitors aren't being caught.

Tune the detection sensitivity

Below the execution mode are four detection controls. The first three are sensitivity levels — each is a dropdown with Off, Low, Medium, and High (shown as 0–3):

  • Request Integrity Sensitivity — how strictly the request itself is checked for signs of automation.
  • IP Address Sensitivity — how heavily a visitor's IP reputation is weighted.
  • Browser Fingerprint Sensitivity — how strictly the visitor's browser fingerprint is scored.

The fourth control, Browser Fingerprint Aggression, is a dropdown with Unknown, Low, Medium, High, and Custom (shown as 0–4). It controls how aggressively the fingerprint check acts on a borderline visitor — higher settings lean toward challenging when the signals are inconclusive. As with the sensitivity controls, raise it gradually and watch the Security Events log.

Warning

Higher sensitivity catches more bots but can also challenge legitimate visitors. Raise these gradually and check the Security Events log for false positives before going further.

Enable complex browser fingerprinting (optional)

The Enable complex browser fingerprinting switch turns on additional browser signals for fingerprinting. It can improve detection but may affect performance on some browsers, so leave it off unless you need the extra accuracy.

Save your changes

Click Save settings to apply your configuration, or Cancel to discard unsaved changes and reload the current settings. A confirmation message appears once the update succeeds.

After saving, you'll see "Bot detection settings have been updated." If the save fails, the page reloads with the settings unchanged and shows the reason.

The same settings are available over the REST API. All parameters are optional — send only the ones you want to change:

curl -X PATCH \
  -H "Authorization: Bearer $SUPERSPACE_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_mode": 1,
    "request_integrity_sensitivity": 2,
    "ip_address_sensitivity": 2,
    "browser_fingerprint_sensitivity": 2,
    "browser_fingerprint_aggression": 2,
    "browser_fingerprint_complex_enabled": true
  }' \
  https://control.superspace.nl/api/sites/$SITE_ID/shield/bot_detection

execution_mode: 0=Log only, 1=Challenge. The three *_sensitivity fields: 0=Off, 1=Low, 2=Medium, 3=High. browser_fingerprint_aggression: 0=Unknown, 1=Low, 2=Medium, 3=High, 4=Custom.

Because Bot Detection is premium-only, the update returns 403 shield_premium_required on a non-premium plan, and a read or write returns 409 shield_not_active if Shield hasn't been activated for the site. See the Shield API reference for the full bot-detection endpoints.

Next steps