---
type: how-to
title: WordPress
summary: "Add Caputchin to a WordPress site with the plugin: install it, paste your keys, pick the forms to protect, and confirm the first server-verified session."
---

Caputchin ships as a WordPress plugin. It adds the widget to your forms and checks every submission on your server before WordPress accepts it, so there is no code to write. It protects these forms out of the box:

- the WordPress comment, login, registration, and lost-password forms,
- Contact Form 7, WPForms, and Fluent Forms.

For any other place, the plugin adds a block and a shortcode. Plan on about 15 minutes from a new account to the first server-verified session.

<Callout type="info">
The plugin needs WordPress 6.0 or later and PHP 7.4 or later, and an administrator account that can install plugins. The plugin source is open: [github.com/Caputchin/caputchin-wordpress](https://github.com/Caputchin/caputchin-wordpress).
</Callout>

## 1. Create a site key

Sign in at [caputchin.com/login](https://caputchin.com/login) (your first sign-in creates the account), open your **Personal** troop, click **Create site-key**, name it after your site, and click **Create**. Copy both values:

- the **public key** (`cpt_pub_...`),
- the **secret** (`cpt_sec_...`). It is shown only once, so paste it somewhere safe until step 3.

A new key accepts every origin, so it works on your site straight away. Before you go live, add your site's origin to the key's **CORS origins** (see [Security](/docs/site-keys/security)), so only your site can use the key. [Create your account and first site key](/docs/getting-started/create-your-account) walks through the same screens with more detail.

## 2. Install the plugin

1. Download `caputchin.zip` from the [latest plugin release](https://github.com/Caputchin/caputchin-wordpress/releases/latest). Do not unzip it.
2. In the WordPress admin, go to **Plugins → Add Plugin**, click **Upload Plugin**, choose `caputchin.zip`, and click **Install Now**.
3. Click **Activate Plugin**.

<Callout type="warn">
The **Login form** is protected as soon as you activate the plugin, and WordPress sign-ins fail until your keys are saved. Stay signed in and go straight on to [Paste your keys](#3-paste-your-keys-and-choose-the-forms). If you are signed out before then, rename the `wp-content/plugins/caputchin` folder (over FTP, SSH, or your host's file manager), sign in, rename it back, and save your keys while you are still signed in.
</Callout>

The widget script ships inside the plugin and is served by your own site. Nothing is loaded from a CDN unless you use a game (see [Use a game](#use-a-game-instead-of-the-checkbox)).

## 3. Paste your keys and choose the forms

Go to **Settings → Caputchin**. The settings page has tabs. Switching tabs reloads the page, so click **Save Changes** before you move to another tab.

1. On the **Keys** tab, paste the public key into **Site key** and the secret into **Secret key**, then click **Save Changes**.
2. Open the **Protected forms** tab. Each form has a **Protect this form** box, and all seven start checked. Uncheck the forms you do not want covered, then click **Save Changes**.

The secret is stored in your WordPress database and used only in the server-to-server check. It is never printed in a page or sent to the browser. The secret field stays empty after saving: leave it blank to keep the saved secret, or paste a new one to replace it.

<Callout type="warn">
Once your keys are saved, keep your admin tab open and sign in from a private window, to confirm the widget appears on the login form and lets you in. Application passwords, XML-RPC, and REST sign-ins are not affected.
</Callout>

The **Appearance** tab sets the theme (auto, light, or dark), size, language, and when the check runs. The defaults suit most sites.

## 4. Form plugins

For Contact Form 7, WPForms, and Fluent Forms, checking the form on the **Protected forms** tab is the whole setup. The plugin adds the widget to every form of that plugin (next to the submit button in WPForms and Fluent Forms, at the end of the form in Contact Form 7) and checks the token when the form is submitted. A submission without a valid token is rejected: WPForms and Fluent Forms show an error on the form, and Contact Form 7 treats it as spam and shows its own failure message (by default, "There was an error trying to send your message"). A WordPress comment without a valid token is refused with "Please complete the verification challenge before submitting." The visitor can try again.

You do not add a field or a shortcode inside the form builder.

## 5. Confirm the first server-verified session

1. Open a protected form on your site in a private window. For example, a post with comments open, or a page with a Contact Form 7 form.
2. Complete the widget if it asks (with the default **Auto** trigger it usually passes on its own, with a check mark), then submit the form.
3. In the [Caputchin dashboard](https://caputchin.com/app), open your troop and click your site key. Refresh the statistics.

**Server-verified** now reads at least `1`: your WordPress server confirmed a token with Caputchin. That is your first verified session. If **Client-completed** went up but **Server-verified** did not, the secret is wrong or the form you used is not checked on the **Protected forms** tab. [Statistics and sessions](/docs/site-keys/statistics) explains each number.

To see the protection itself, submit the same form with the widget not completed. WordPress rejects it.

## Place the widget anywhere else

For a form the plugin does not cover, or any page or post:

- In the block editor, add the **Caputchin** block (the checkbox) or the **Caputchin Game** block.
- In any content, use the `[caputchin]` shortcode (the checkbox) or `[caputchin-game]` (a game).

Inside a form, the widget adds a hidden `caputchin-token` field. The plugin checks it only on the forms listed above. For your own form handler, confirm the token on your server as described in [Verify on your backend](/docs/integration-guides/verify-on-your-backend). The plugin's **Guide** tab lists every shortcode attribute.

## Use a game instead of the checkbox

The **Game** tab sets the default game and layout for the `[caputchin-game]` shortcode and the **Caputchin Game** block, for example `caputchin/games/leaf-memory`. Games are listed in the [marketplace](https://caputchin.com/marketplace). A game is loaded from jsDelivr, checked against an integrity hash, and run in a sandboxed frame.

<Callout type="warn">
If your site key has **Require a game to verify** turned on, the checkbox cannot pass on that key, so place the game with the block or shortcode. See [the game gate](/docs/site-keys/games).
</Callout>

## Troubleshooting

- **The widget does not appear on a form.** Check that the form is checked on the **Protected forms** tab and that **Save Changes** was clicked. A page cache can serve the old page: clear it after saving.
- **Every submission is rejected.** The secret does not match the site key. Paste the secret again (or rotate it on the key's **Settings** page in the dashboard and paste the new one).
- **The widget works on one address but not another.** When the key's **CORS origins** list is not empty, it must include every origin the site is served from (for example both `https://example.com` and `https://www.example.com`). See [Security](/docs/site-keys/security).

## See also

- [Site keys overview](/docs/site-keys/overview)
- [Statistics and sessions](/docs/site-keys/statistics)
- [Keycloak](/docs/integration-guides/keycloak)