WordPress

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.

1. Create a site key

Sign in at 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), so only your site can use the key. Create your account and first site key walks through the same screens with more detail.

2. Install the plugin

1. Download caputchin.zip from the latest plugin release. 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.

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).

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.

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, 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 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. 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. A game is loaded from jsDelivr, checked against an integrity hash, and run in a sandboxed frame.

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.

See also

• Site keys overview
• Statistics and sessions
• Keycloak