Configuration
Configuring the ALTCHA WordPress plugin gives you fine-grained control over how your site is protected against bots, spam, and malicious traffic.
This guide walks through the available settings — from basic operation modes to advanced firewall and analytics options — so you can tune the plugin for the right balance of security and performance.
General settings
Mode of operation
The plugin can operate in two modes: Standard or Sentinel.
- Standard — recommended for most users. Provides effective protection using ALTCHA's proof-of-work system. Fully self-contained, requires no external services, and secures your site with no additional configuration.
- Sentinel — for advanced security needs, ALTCHA Sentinel delivers comprehensive protection against bots and malicious attacks. Requires either a self-hosted ALTCHA Sentinel instance or the managed ALTCHA Cloud SaaS.
Verification bypass
You can configure whether logged-in users must be verified, or can bypass verification for a faster experience.
- Whitelisted IP addresses can also bypass verification.
- Logged-in admin users are always excluded from verification.
Actions
Actions are any WordPress submissions or operations that handle user input. The ALTCHA interceptor monitors these requests and performs verification. You can configure it to:
- Intercept specific actions by name
- Intercept all actions
- Exclude certain actions
To configure actions, enter their names in the input field, one per line.
- Use the wildcard
*to match any string. - Prefix an action with
!to exclude it.
Detecting actions
By default, the action field name is action, which is common in WordPress. Some plugins, however, use non-standard parameters — WooCommerce, for example, uses wc-ajax. To detect these, use the field name followed by an equals sign, e.g. wc-ajax=* matches all actions submitted in the wc-ajax field.
Examples:
| Pattern | Matches |
|---|---|
* | All actions |
action_name | An exact action |
action_* | All actions starting with action_ |
!action_name | Excludes a specific action |
!action_* | Excludes all actions starting with action_ |
wc-ajax=* | All WooCommerce AJAX actions |
Paths
Like Actions, Paths let you require verification for AJAX requests and standard form submissions, matched by URL path instead of a field value.
Examples:
| Pattern | Matches |
|---|---|
* | All paths |
/wp-json/plugin-name | An exact path |
/wp-json/plugin-name/* | All paths under /wp-json/plugin-name/ |
!/wp-json/plugin-name | Excludes that exact path |
!/wp-json/plugin-name/* | Excludes everything under /wp-json/plugin-name/ |
Inject paths
The ALTCHA interceptor must be injected into every page that requires protection. The Inject Paths setting defines where the interceptor is injected, and which paths to exclude — helping reduce page size on pages that don't need verification (static pages, for example).
If the interceptor isn't injected into a page, verification won't work there.
Analytics
Verification requests are logged to the WordPress database. Logging can generate a significant amount of data, so you may want to limit or disable parts of it:
- Challenge Requests — logs challenges (
/wp-json/altcha/v1/challenge). - Blocked Requests — logs requests blocked by the Firewall.
You can also disable analytics entirely.
Data retention
Analytics data is stored for 90 days by default, after which it's deleted automatically. Lower retention periods reduce database size and improve performance.
The events table also lets you export events for a selected time period as a CSV file, for external use or archiving.
Firewall
The Firewall lets you block requests based on IP address, country of origin, or User-Agent. It also provides rate limiting to prevent abuse.
Blocking requests
You can block by:
- IP addresses — one per line.
- Countries — ISO 3166-1 alpha-2 codes, one per line.
- User-Agents — one per line, supports wildcards (
*).
Behavior depends on Under Attack Mode:
- Inactive — blocking applies only to non-viewer (POST) requests.
- Active — blocking also applies to viewer (GET) requests.
Rate limiting
Rate limiting restricts how many requests a visitor can make in a given time window, protecting forms and actions from spam floods and abuse.
- Rate limits always apply to non-viewer (POST) requests, even in Under Attack Mode.
- Limits use WordPress transients — for best performance, enable Redis or Memcached.
Keys
Rate limits can be applied based on:
- EDK (Ephemeral Device Key) — a temporary, GDPR-compliant identifier, valid for up to 24 hours.
- IP — the visitor's IP address.
- User ID — the logged-in user's ID (falls back to IP for anonymous users).
Because EDKs are valid for a maximum of 24 hours, a rate limit window can't exceed 24 hours either.
Discriminator
Rate limits can be:
- Global — applied to all requests.
- Action-specific — applied only to configured actions.
- Path-specific — applied only to certain paths.
Limit
Rate limits are defined as requests/window.
Examples:
| Limit | Meaning |
|---|---|
1/10s | Max 1 request per 10 seconds |
10/10m | Max 10 requests per 10 minutes |
50/1h | Max 50 requests per 1 hour |
5/1d | Max 5 requests per 24 hours |
Next steps
- Advanced — hooks and filters for overriding any of these settings programmatically.
- Troubleshooting — if verification isn't behaving as configured.