# 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](/docs/sentinel/) instance or the managed [ALTCHA Cloud](/docs/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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), one per line.
- **User-Agents** — one per line, supports wildcards (`*`).

Behavior depends on [Under Attack Mode](/docs/wordpress/features/#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](/docs/sentinel/security/privacy-protection/#ephemeral-device-keys-edk)) — 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](/docs/wordpress/advanced/)** — hooks and filters for overriding any of these settings programmatically.
- **[Troubleshooting](/docs/wordpress/troubleshooting/)** — if verification isn't behaving as configured.