WordPress Plugin
Install and configure the BlockBots WordPress plugin to protect your site from bots, scrapers, VPNs, proxies, and browser emulators.
Overview
The BlockBots WordPress plugin protects your site against bots, spam traffic, scrapers, VPNs, proxies, and browser emulators. It runs at WordPress init priority 0 — intercepting requests before most of WordPress processes them — keeping overhead minimal.
The plugin operates in two tiers:
| Tier | Features |
|---|---|
| Free | User-agent whitelisting, login page protection, rate limiting, known-bad-bot blocking |
| PRO | API-based cloud verification, deep bot detection, VPN/proxy/emulator blocking, management panel with advanced filters |
Requirements
- WordPress 4.6 or higher
- PHP 7.2 or higher (required for EdDSA JWT support)
- Composer dependency:
firebase/php-jwt ^7.0— included in the plugin'svendor/directory - PRO only: a valid BlockBots API key from blockbots.org
Installation
- Upload the
blockbotsfolder to/wp-content/plugins/, or install via WP Admin → Plugins → Add New. - Activate the plugin through WP Admin → Plugins.
- The plugin automatically creates a database table (
{prefix}blockbots) and schedules cron jobs on activation. - Navigate to WP Admin → Blockbots to configure settings.
- PRO only: Enter your API key on the Pro Features tab to unlock cloud-based verification.
Free and Pro versions cannot be active at the same time. Deactivate one before activating the other.
How it works
Every front-end request goes through the following flow:
1. Abort checks
Requests are skipped for AJAX, cron jobs, logged-in users (if Ignore Logged-In Users is enabled), and the login page (if Protect Login Page is disabled).
2. Free mode (no API key)
- The visitor's user agent is checked against the whitelist. Whitelisted bots (Googlebot, Bingbot, etc.) pass through automatically.
- Rate limiting applies: more than 10 requests from the same IP within 10 seconds triggers a block.
3. PRO mode (API key configured)
- If the visitor already has a valid
__bbjwtJWT cookie, they pass through instantly — no API call made. - If a block decision cookie (
__bb_decision) is present, the block page is shown immediately. - Otherwise, the visitor sees a verification page. The BlockBots JS library runs a silent cloud check. Humans are issued a signed JWT cookie; bots are blocked. The experience typically takes under 1–2 seconds.
Free features
Configure under WP Admin → Blockbots → Free Features.
Protect WP Login Page
Enables bot verification on wp-login.php. Default: OFF.
Ignore Logged-In Users
Skips bot checks for visitors with an active WordPress session. Recommended: ON to prevent admin lockout. Default: ON.
Block Known Bad Bots Blocks all user agents not found in the whitelist. Works automatically via the whitelist mechanism — no separate toggle.
Whitelist User Agents Add custom user-agent strings to allow, one per line. These are merged with the built-in whitelist. Matching is case-insensitive and partial (substring match).
MyMonitorBot
MyUptimeChecker
Your browser's current user agent is shown below the textarea for reference.
PRO features
Unlocked by entering a valid API key. Configure under WP Admin → Blockbots → Pro Features.
Get your API key at blockbots.org.
| Feature | Description |
|---|---|
| Deep Bot Detection | Behavioral analysis and signature matching beyond user-agent checks |
| Real-time Cloud Protection | Checks IPs against a live database of known malicious bots |
| Detect VPN Connection | Identifies and blocks visitors connecting via VPN services |
| Detect Proxy Connection | Identifies open, datacenter, and residential proxy connections |
| Detect Emulators | Identifies headless browsers and automation tools (Puppeteer, Selenium, Playwright) |
| Management Panel | Access to panel.blockbots.org with filters by country, OS, browser, and language |
| Show Loading Indicator | Displays an animated overlay while cloud verification runs |
API key format: 20+ alphanumeric characters. The dashboard shows a masked version (first 4 and last 4 characters) once saved.
Uninstalling
- Deactivate the plugin in WP Admin → Plugins.
- Delete the plugin from WP Admin → Plugins.
The uninstall routine automatically deletes all plugin options from wp_options, cancels all scheduled cron events, and drops the {prefix}blockbots database table. No data is left behind.