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_enableandmu_enablestay mutually exclusive. Turning one on turns the other off, and the MU loader file is installed or removed to match.block_rknschedules a threat-list refresh when it turns on.redis_enable,memcached_enableandapcu_enableprobe 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:
checkis the master bot check.botblocker_force_checkchecks every page load, including logged-in users and whitelisted visitors.skip_logged_in_usersextends the bypass to all logged-in roles.allow_self_ip_reqlets the server call itself.allow_self_call_headersigns outgoing self-calls.allow_app_password_restlets valid application passwords skip the shield.autosave_admin_ipsaves administrator addresses to the trusted list.options_preflightpasses CORS preflight requests.iframe_stopblocks framed access.check_get_refinspects GET parameters in the referrer.bbcs_ddos_resiliencehardens the verification cycle behind a WAF or CDN.
Bot detection:
block_simplebot_ua,block_empty_ua,block_empty_lang,block_http10_usersblock_fake_ref,block_incorrect_lang_users,block_ip_ptr_matchblock_cf_users,block_proxy_users,block_ipv6_usersblock_adblocker_users,block_incognito_users,block_simple_antidetectfingerprint_sticky_block,whitelist_whatsapp_previewget_browser_type,get_device_type,get_os_typebbcs_allow_empty_accept_langbbcs_edge_autotrust(turning it off revokes every auto-trusted edge immediately)
CAPTCHA:
bbcs_honeypot_enabledrecaptcha_checkbbcs_captcha_img_inlinerecaptcha_v3_ipv6_block
Cookies and headers:
session_token_enabled,vary_cookienoarchive,utm_noindex,utm_referrerbbcs_cors_strict_headers
Cloud and caching:
force_cloud_validation,cloud_fallback_blocktransients_enable,cache_ui_dataredis_enable,memcached_enable,apcu_enable
Logging:
botblocker_log_error,botblocker_log_admin,botblocker_log_allowbotblocker_log_bbcs,botblocker_log_block,botblocker_log_clibotblocker_log_disabled,botblocker_log_fake,botblocker_log_goodipbotblocker_log_local,botblocker_log_tests,botblocker_log_wpaudit_log_enable
Account, payment and layers:
login_brutforce_enabledpayment_bypass_enable,payment_bypass_logpayment_strict_method,payment_keep_ip_rulesbbcs_2fa_enable,bbcs_2fa_xmlrpc_blockmu_enable,mu_geo_enableearly_init_enable,early_geo_enable,early_cache_gate
Rate limiting, TLS and reverse DNS:
bbcs_rate_check_enabled,bbcs_rate_subnet_enabledtls_fingerprint_checkptr_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:
disablebelongs tobotblocker/set-protection.secure_modebelongs tobotblocker/set-secure-mode.bbcs_captcha_modeandbbcs_captcha_waitbelong tobotblocker/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 andbbcs_wp_abilities_enabledstay 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.