Skip to main content

reCAPTCHA Integration

Assemble Web supports Google reCAPTCHA v3 for email-and-password registration. The integration is opt-in per environment. Login, forgot-password, and reset-password intentionally remain available when reCAPTCHA is enabled.

Environment Variables​

VariableScopeRequiredDescription
NEXT_PUBLIC_RECAPTCHA_ENABLEDClientYesSet to 'true' to protect registration. Any other value disables it.
NEXT_PUBLIC_RECAPTCHA_KEYClientYes (when enabled)The site key from the Google reCAPTCHA Admin Console. The key is exposed to the browser.

The middleware owns the reCAPTCHA secret, score threshold, and verification policy. Web must not receive or verify those values.

Registration Flow​

When registration is submitted, Web generates one short-lived token with grecaptcha.execute() using the stable v3 action register and forwards it as X-Recaptcha-Token on the middleware registration request. The middleware verifies that token with Google, rejects responses whose action is not register, and accepts or rejects the registration.

Registration submit
       |
       v
grecaptcha.execute() --> token
       |
       v
POST /user/register + X-Recaptcha-Token
       |
       v
Middleware --> Google siteverify --> accept or reject

A token is generated and verified exactly once. Verifying it in both Web and the middleware is invalid because reCAPTCHA tokens are single-use and the second verification returns timeout-or-duplicate.

If the reCAPTCHA script is unavailable, execution fails, or no token is returned within ten seconds, registration fails closed and shows the generic API error. The login and password-recovery flows are unaffected.

Disclosure​

When reCAPTCHA is active, the registration form displays the captcha_disclaimer localization value. It falls back to This site is protected by reCAPTCHA. until the CMS dictionary contains the key.

Disabling reCAPTCHA​

Set NEXT_PUBLIC_RECAPTCHA_ENABLED to any value other than 'true', or omit it. Registration then follows its normal path without generating a token. This is the safe environment-level rollback if the site key, Google connectivity, or middleware verification is not ready.