Skip to content
ALTCHA ALTCHA ALTCHA

Configure WordPress Plugin

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 you 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. Standard mode provides effective protection using ALTCHA’s proof-of-work system. It is fully self-contained, requires no external services, and secures your website without additional configuration.

  • Sentinel
    For advanced security needs, ALTCHA Sentinel delivers comprehensive protection against bots and malicious attacks. Requires an ALTCHA Sentinel instance.

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. For example, WooCommerce uses wc-ajax.

To detect these, use the field name followed by an equals sign. Example:

  • wc-ajax=*: matches all actions submitted in the wc-ajax field

Examples:

  • *: matches all actions
  • action_name: matches an exact action
  • action_*: matches all actions starting with action_
  • !action_name: excludes a specific action
  • !action_*: excludes all actions starting with action_
  • wc-ajax=*: matches all WooCommerce AJAX actions

Paths

The ALTCHA interceptor must be injected into every page that requires protection.

The Paths configuration allows you to define where the interceptor is injected and which paths to exclude.

This helps reduce page size when verification is not needed (e.g., static pages).

If the interceptor is not injected into a page, verification will not work there.

Examples:

  • *: all paths
  • /contact-us: exact path
  • /forms/*: all paths under /forms/
  • !/about: excludes /about
  • !/shop/*: excludes everything under /shop/

Analytics

Verification requests are logged into the WordPress database.

Logging can generate a significant amount of data, so you may want to limit or disable certain options:

  • 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 is automatically deleted. Lower retention periods reduce database size and improve performance.

Firewall

The Firewall allows you to 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:

  • When Under Attack Mode is inactive, blocking applies only to non-viewer (POST) requests.
  • When Under Attack Mode is active, blocking also applies to viewer (GET) requests.

Rate Limiting

Rate limiting restricts how many requests a user can make in a given time window.

This protects 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): temporary, GDPR-compliant identifier (valid up to 24h)
  • IP: user’s IP address
  • User ID: logged-in user’s ID (fallback to IP for anonymous users)

Since EDKs are valid for a maximum of 24h, the duration of a rate limit window cannot exceed 24 hours.

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:

  • 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