Switch settings from a client

botblocker/set-setting turns one boolean protection setting on or off. It uses the same save path as the Dashboard, so the settings row, the generated runtime file and the running plugin all end up with the same value.

Use it when a client has to walk through protection modes without a person clicking toggles. A test stand that checks the plugin and its add-ons under different combinations is the main case.

To publish the ability, open BotBlocker → Integrations → WP Abilities API, turn on the master switch, then turn on Change a switch setting. Both switches are off by default.

What a call changes

The ability writes the setting row in the BotBlocker settings table, rebuilds settings.php in the data folder, and updates the settings object that the current request already holds. Early protection reads settings.php before WordPress loads, so skipping the rebuild would leave the first layer on the old value.

A few settings have extra work attached, and the ability does it the same way the Dashboard does:

  • early_init_enable and mu_enable stay mutually exclusive. Turning one on turns the other off, and the MU loader file is installed or removed to match.
  • block_rkn schedules a threat-list refresh when it turns on.
  • redis_enable, memcached_enable and apcu_enable probe the backend first. If the probe fails, the switch stays off and the call returns an error instead of storing a dead integration.

Confirmation, dry runs and limits

Each call needs confirm set to SET. Without it the ability refuses the call and writes nothing.

dry_run: true reports the value it would write and what would change, then stops. Use it before a batch of real calls.

The ability is rate limited like the other destructive abilities. Every call made by a signed-in user is written to the audit log with the setting name, the old value and the new value.

Answer fields

Field Meaning
key The setting that was asked for.
previous The value before the call.
enabled The effective value after the call.
changed Whether the value differs from the previous one.
applied Whether this call wrote the row. A dry run and a refused PRO switch leave it false.
reason Empty on success, license when a PRO switch is not covered by the active license.
protection_enabled Whether BotBlocker protection itself is on.

Settings you can change

Only the keys in this list are accepted. Everything else is refused with ability_invalid_input.

Protection and request checks:

  • check is the master bot check.
  • botblocker_force_check checks every page load, including logged-in users and whitelisted visitors.
  • skip_logged_in_users extends the bypass to all logged-in roles.
  • allow_self_ip_req lets the server call itself.
  • allow_self_call_header signs outgoing self-calls.
  • allow_app_password_rest lets valid application passwords skip the shield.
  • autosave_admin_ip saves administrator addresses to the trusted list.
  • options_preflight passes CORS preflight requests.
  • iframe_stop blocks framed access.
  • check_get_ref inspects GET parameters in the referrer.
  • bbcs_ddos_resilience hardens the verification cycle behind a WAF or CDN.

Bot detection:

  • block_simplebot_ua, block_empty_ua, block_empty_lang, block_http10_users
  • block_fake_ref, block_incorrect_lang_users, block_ip_ptr_match
  • block_cf_users, block_proxy_users, block_ipv6_users
  • block_adblocker_users, block_incognito_users, block_simple_antidetect
  • fingerprint_sticky_block, whitelist_whatsapp_preview
  • get_browser_type, get_device_type, get_os_type
  • bbcs_allow_empty_accept_lang
  • bbcs_edge_autotrust (turning it off revokes every auto-trusted edge immediately)

CAPTCHA:

  • bbcs_honeypot_enabled
  • recaptcha_check
  • bbcs_captcha_img_inline
  • recaptcha_v3_ipv6_block

Cookies and headers:

  • session_token_enabled, vary_cookie
  • noarchive, utm_noindex, utm_referrer
  • bbcs_cors_strict_headers

Cloud and caching:

  • force_cloud_validation, cloud_fallback_block
  • transients_enable, cache_ui_data
  • redis_enable, memcached_enable, apcu_enable

Logging:

  • botblocker_log_error, botblocker_log_admin, botblocker_log_allow
  • botblocker_log_bbcs, botblocker_log_block, botblocker_log_cli
  • botblocker_log_disabled, botblocker_log_fake, botblocker_log_goodip
  • botblocker_log_local, botblocker_log_tests, botblocker_log_wp
  • audit_log_enable

Account, payment and layers:

  • login_brutforce_enabled
  • payment_bypass_enable, payment_bypass_log
  • payment_strict_method, payment_keep_ip_rules
  • bbcs_2fa_enable, bbcs_2fa_xmlrpc_block
  • mu_enable, mu_geo_enable
  • early_init_enable, early_geo_enable, early_cache_gate

Rate limiting, TLS and reverse DNS:

  • bbcs_rate_check_enabled, bbcs_rate_subnet_enabled
  • tls_fingerprint_check
  • ptr_cache_in_db

PRO switches are on the list too: hosting_block, block_device_options, block_web_engine_options, block_override, block_vpn_users, block_tor_users, block_rkn. Without a matching license the call does not turn them on. It answers applied: false and reason: license, which is what the Dashboard does when a save tries to keep a PRO value without a license.

Settings that are refused

Some settings have their own ability, and some must never be written by a client:

  • disable belongs to botblocker/set-protection.
  • secure_mode belongs to botblocker/set-secure-mode.
  • bbcs_captcha_mode and bbcs_captcha_wait belong to botblocker/set-captcha-mode.
  • Secrets stay out: salt, secret_botblocker_get_param, action_disable, action_off, action_on, the Cloud keys and passwords, the reCAPTCHA keys, and the cache passwords.
  • Every bbcs_ability_* switch and bbcs_wp_abilities_enabled stay out. A client must not be able to publish or hide its own abilities.
  • Numbers and strings that decide site behavior are not switches: hits_per_user, time_ban, header_error_code, cookie, samesite, timeouts and thresholds.

Examples

Turn the master bot check off before a baseline run:

wp eval '
$result = wp_get_ability( "botblocker/set-setting" )->execute( array(
	"key"     => "check",
	"enabled" => false,
	"confirm" => "SET",
	"reason"  => "baseline run",
) );
print_r( $result );
'

The answer reports previous: true, enabled: false and applied: true. The settings table now holds check = 0, and so does settings.php.

Check what a change would do without writing it:

wp eval '
$result = wp_get_ability( "botblocker/set-setting" )->execute( array(
	"key"     => "bbcs_honeypot_enabled",
	"enabled" => true,
	"confirm" => "SET",
	"dry_run" => true,
) );
print_r( $result );
'

Here changed is true when the value differs, and applied stays false.

Call the same ability over REST, signed in as an administrator:

curl -X POST "https://example.com/wp-json/wp-abilities/v1/abilities/botblocker/set-setting/run" \
  -u "admin:application-password" \
  -H "Content-Type: application/json" \
  -d '{"key":"early_cache_gate","enabled":1,"confirm":"SET"}'

An administrator application password works for the request. The ability itself still needs manage_options.

Turn MU mode on while Early Init is on:

wp eval '
$result = wp_get_ability( "botblocker/set-setting" )->execute( array(
	"key"     => "mu_enable",
	"enabled" => true,
	"confirm" => "SET",
) );
print_r( $result );
'

The answer is applied: true, and early_init_enable reads 0 afterwards. The MU loader is in place because the Dashboard would have done that too.

Errors

Code When
ability_confirmation_required confirm was missing or not SET.
ability_invalid_input The key is not on the allow list, or enabled was not sent.
ability_backend_unavailable A cache backend did not answer the probe. The switch stays off.
ability_rate_limited Too many destructive calls in a short time.
ability_execution_failed The settings row could not be written.
rest_forbidden The caller is not an administrator.

If a change seems to have no effect

Turn on the ability switch first, then the master switch. The master switch off means nothing is registered, so the call never reaches the plugin.

For Early Init and MU mode, check botblocker/get-layer-state. It reports which layer answers and whether the router or the MU loader is deployed.

If a cache backend refuses to turn on, the reason is the connection probe. Fix the host or port under the cache settings, then try again.

Change a switch setting

Default: Off

This switch publishes botblocker/set-setting. Turn it on only for a client you control, and only while a test stand needs it. A client with this ability can change protection settings within the allow list above, and it acts with administrator rights.

  • On: the ability is registered whenever the master switch is on.
  • Off: the ability does not exist for REST, MCP or AI clients.

Related pages: WordPress abilities and connectors.