{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/captcha-supertokens", "result": {"data":{"markdownRemark":{"html":"

Bot traffic targeting authentication endpoints represents a persistent security challenge. Automated account creation, credential stuffing attacks, and fake registrations consume resources, pollute user databases, and expose applications to fraud. CAPTCHA (Completely\nAutomated Public Turing test to tell Computers and Humans Apart) provides a standard defense mechanism by requiring human interaction\nbefore processing authentication requests.

\n

Traditional CAPTCHA integration requires coordinating frontend widget libraries, backend token validation, error handling, and provider-specific API calls across signup, login, and password reset flows. This scattered implementation increases maintenance burden and creates coupling between authentication logic and bot prevention mechanisms.

\n

SuperTokens addresses this complexity through a plugin architecture that isolates CAPTCHA logic from core authentication. The plugin model enables developers to add CAPTCHA protection to specific endpoints and signup forms, login pages,\npassword reset flows with minimal wiring. Configuration changes control which APIs enforce CAPTCHA, which provider handles verification, and under what conditions challenges appear, all without modifying authentication business logic.

\n

This article demonstrates practical CAPTCHA integration patterns, explains server-side verification requirements, and shows how SuperTokens’ plugin system simplifies deployment across multiple authentication flows.

\n

I Want to Protect My Signup Form From Bots. How Do I Integrate CAPTCHA?

\n

Bot-driven fake account creation inflates user counts, triggers verification emails that land in spam folders, and creates opportunities\nfor downstream abuse. Signup forms represent the highest-value target for CAPTCHA protection.

\n

Frontend Integration

\n

CAPTCHA integration begins with embedding the provider’s widget on the signup form. The widget renders a challenge (image selection, checkbox interaction, or invisible background verification) and generates a token upon successful completion.

\n

Basic Frontend Flow:

\n
    \n
  1. User completes signup form fields (email, password)
    2. \n
  2. CAPTCHA widget loads and displays challenge
    3. \n
  3. User solves challenge; widget generates verification token
    4. \n
  4. Frontend sends signup request with CAPTCHA token included
    5. \n
  5. Backend validates token before creating account
    6. \n
\n

The CAPTCHA widget should appear only where required. Showing challenges on every page degrades user experience without benefiting security. Selective placement—signup form only, not login page—reduces friction while protecting the highest-risk endpoint.

\n

SuperTokens Frontend Integration:

\n

SuperTokens’ frontend SDK accepts CAPTCHA plugins that inject widgets automatically at specified forms. First, install the plugin:

\n\n \n \n \n \n
npm install supertokens-auth-react @supertokens-plugins/captcha-react
\n

Then configure the plugin in your SuperTokens initialization:

\n\n \n \n \n \n
// frontend/src/supertokensConfig.js\nimport SuperTokens from \"supertokens-auth-react\";\nimport EmailPassword from \"supertokens-auth-react/recipe/emailpassword\";\nimport Session from \"supertokens-auth-react/recipe/session\";\nimport CaptchaPlugin from \"@supertokens-plugins/captcha-react\";\nSuperTokens.init({\n  appInfo: {\n    appName: \"SuperTokens Demo\",\n    apiDomain: \"http://localhost:3001\",\n    websiteDomain: \"http://localhost:3000\",\n    apiBasePath: \"/auth\",\n    websiteBasePath: \"/auth\",\n  },\n  useShadowDom: false,\n  recipeList: [\n    EmailPassword.init(),\n    Session.init(),\n  ],\n  experimental: {\n    plugins: [\n      CaptchaPlugin.init({\n        type: \"reCAPTCHAv3\",\n        captcha: {\n          sitekey: \"YOUR_RECAPTCHA_SITE_KEY\",\n        },\n      }),\n    ],\n  },\n});
\n

Important: Set useShadowDom: false when using CAPTCHA plugins to ensure proper widget rendering.

\n

Initialize your React application with SuperTokens:

\n\n \n \n {getSuperTokensRoutesForReactRouterDom(reactRouterDom, [\n EmailPasswordPreBuiltUI,\n ])}\n {/* your app routes */}\n \n \n \n );\n}\nconst root = createRoot(document.getElementById("root"));\nroot.render();`, `26760281016401244000`)\"\n >\n \n \n \n \n
// frontend/src/index.js\nimport React from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport { BrowserRouter, Routes } from \"react-router-dom\";\nimport SuperTokens, { SuperTokensWrapper } from \"supertokens-auth-react\";\nimport { getSuperTokensRoutesForReactRouterDom } from \"supertokens-auth-react/ui\";\nimport { EmailPasswordPreBuiltUI } from \"supertokens-auth-react/recipe/emailpassword/prebuiltui\";\nimport * as reactRouterDom from \"react-router-dom\";\nimport \"./supertokensConfig\";\nfunction App() {\n  return (\n    <SuperTokensWrapper>\n      <BrowserRouter>\n        <Routes>\n          {getSuperTokensRoutesForReactRouterDom(reactRouterDom, [\n            EmailPasswordPreBuiltUI,\n          ])}\n          {/* your app routes */}\n        </Routes>\n      </BrowserRouter>\n    </SuperTokensWrapper>\n  );\n}\nconst root = createRoot(document.getElementById(\"root\"));\nroot.render(<App />);
\n

This configuration automatically handles CAPTCHA widget rendering, token capture, and inclusion in API requests. No manual DOM manipulation or event handler wiring required.

\n

Backend Token Validation

\n

Frontend CAPTCHA widgets generate tokens that must be verified server-side before processing requests. Relying on client-side validation alone provides no security—attackers can trivially bypass frontend checks or submit requests directly to the API.

\n

Backend Validation Requirements:

\n
    \n
  • Extract CAPTCHA token from request payload
    • \n
  • Submit token to provider’s verification API with secret key
    • \n
  • Verify response indicates successful human verification
    • \n
  • Reject request if verification fails or token is invalid
    • \n
\n

SuperTokens Backend Integration:

\n

Install the backend plugin:

\n\n \n \n \n \n
npm install supertokens-node @supertokens-plugins/captcha-nodejs
\n

Configure your Express server with SuperTokens and CAPTCHA validation:

\n{ \n // Enforce CAPTCHA only for signup requests\n return api === "signUpPOST";\n },\n }),\n ],\n },\n});\n\n// -------------------------------------------------------------------\n// CORS configuration\n// IMPORTANT: Must be registered BEFORE SuperTokens middleware\n// -------------------------------------------------------------------\n\napp.use(\n cors({\n origin:WEBSITE_DOMAIN,\n credentials:true,\n allowedHeaders:[\n "content-type",\n ...SuperTokens.getAllCORSHeaders()\n ],\n })\n);\n\n// -------------------------------------------------------------------\n// SuperTokens middleware\n// Handles authentication APIs and session verification\n// -------------------------------------------------------------------\n\napp.use(middleware());\n\n// -------------------------------------------------------------------\n// Application routes\n// -------------------------------------------------------------------\n\napp.get("/ping", (req, res) => {\n res.json({ ok: true });\n});\n\n// -------------------------------------------------------------------\n// SuperTokens error handler\n// IMPORTANT: Must come AFTER all routes\n// -------------------------------------------------------------------\n\napp.use(errorHandler());\n\n// -------------------------------------------------------------------\n// Custom application error handler\n// -------------------------------------------------------------------\napp.use((err, req, res, next) => {\n console.error(err);\n res.status(500).json({ message: "Internal server error" });\n});\n\n// -------------------------------------------------------------------\n// Start the server\n// -------------------------------------------------------------------\napp.listen(3001, () => {\n console.log("🚀 Backend running on http://localhost:3001");\n});`, `45790633935066595000`)\"\n >\n \n \n \n \n
// backend/server/index.js\nimport express from \"express\";\nimport cors from \"cors\";\n\n// Core SuperTokens imports\nimport SuperTokens from \"supertokens-node\";\nimport { middleware,errorHandler } from \"supertokens-node/framework/express\";\n\n// SuperTokens recipes\nimport Session from \"supertokens-node/recipe/session\";\nimport EmailPassword from \"supertokens-node/recipe/emailpassword\";\n\n// CAPTCHA plugin (Node.js)\nimport CaptchaPlugin from \"@supertokens-plugins/captcha-nodejs\";\n\n// -------------------------------------------------------------------\n// Express app setup\n// -------------------------------------------------------------------\n\nconst app=express();\n\n// Parse incoming JSON requests\napp.use(express.json());\n\n// -------------------------------------------------------------------\n// Application configuration\n// -------------------------------------------------------------------\n\nconst API_DOMAIN=\"http://localhost:3001\";\nconst WEBSITE_DOMAIN=\"http://localhost:3000\";\n\n// -------------------------------------------------------------------\n// SuperTokens initialization\n// -------------------------------------------------------------------\n\nSuperTokens.init({\n  framework:\"express\",\n\n  // Connection to SuperTokens Core\n  supertokens:{\n    connectionURI:\"https://try.supertokens.io\"\n  },\n\n  // App metadata shared between frontend and backend\n  appInfo:{\n    appName:\"SuperTokens Demo\",\n    apiDomain:API_DOMAIN,\n    websiteDomain:WEBSITE_DOMAIN,\n    apiBasePath:\"/auth\",\n    websiteBasePath:\"/auth\"\n  },\n\n  // Authentication recipes\n  recipeList:[\n    EmailPassword.init(), // Email + password authentication\n    Session.init(),       // Session management\n  ],\n\n  // Experimental features (plugins)\n  experimental:{\n    plugins:[\n      CaptchaPlugin.init({\n\n        // CAPTCHA provider type\n        type:\"reCAPTCHAv3\",\n\n        // Provider configuration\n        captcha:{\n          secretKey:process.env.RECAPTCHA_SECRET_KEY\n        },\n\n        // Decide when CAPTCHA should be enforced\n        shouldValidate:(api)=>{          \n          // Enforce CAPTCHA only for signup requests\n          return api === \"signUpPOST\";\n        },\n      }),\n    ],\n  },\n});\n\n// -------------------------------------------------------------------\n// CORS configuration\n// IMPORTANT: Must be registered BEFORE SuperTokens middleware\n// -------------------------------------------------------------------\n\napp.use(\n  cors({\n    origin:WEBSITE_DOMAIN,\n    credentials:true,\n    allowedHeaders:[\n      \"content-type\",\n      ...SuperTokens.getAllCORSHeaders()\n    ],\n  })\n);\n\n// -------------------------------------------------------------------\n// SuperTokens middleware\n// Handles authentication APIs and session verification\n// -------------------------------------------------------------------\n\napp.use(middleware());\n\n// -------------------------------------------------------------------\n// Application routes\n// -------------------------------------------------------------------\n\napp.get(\"/ping\", (req, res) => {\n  res.json({ ok: true });\n});\n\n// -------------------------------------------------------------------\n// SuperTokens error handler\n// IMPORTANT: Must come AFTER all routes\n// -------------------------------------------------------------------\n\napp.use(errorHandler());\n\n// -------------------------------------------------------------------\n// Custom application error handler\n// -------------------------------------------------------------------\napp.use((err, req, res, next) => {\n  console.error(err);\n  res.status(500).json({ message: \"Internal server error\" });\n});\n\n// -------------------------------------------------------------------\n// Start the server\n// -------------------------------------------------------------------\napp.listen(3001, () => {\n  console.log(\"🚀 Backend running on http://localhost:3001\");\n});
\n

The shouldValidate function controls which endpoints require CAPTCHA verification. Returning true for signUpPOST enables protection on account creation while leaving login endpoints unaffected.

\n

\n \n failedLoginCache.delete(email), 3600000);\n}\n\n\nconst shouldValidate: ShouldValidate = (api, input) => {\n // Only require CAPTCHA for sign up\n if (api === 'signUpPOST') {\n return true;\n }\n\n\n // Check request headers for suspicious activity\n if (api === 'signInPOST') {\n const userAgent = input.options.req.getHeaderValue('user-agent');\n if (!userAgent || userAgent.includes('bot')) {\n return true;\n }\n\n\n // Optional: Check failed login history\n const emailField = input.formFields?.find(f => f.id === 'email');\n if (emailField) {\n const failedCount = getFailedLoginCount(emailField.value);\n if (failedCount >= 3) {\n return true;\n }\n }\n\n\n return false;\n }\n\n\n return false;\n};\n\n\nSuperTokens.init({\n supertokens: {\n connectionURI: '...',\n },\n appInfo: {\n // your app info\n },\n recipeList: [\n // your recipes\n ],\n experimental: {\n plugins: [\n CaptchaPlugin.init({\n type: 'reCAPTCHAv3', // or "reCAPTCHAv2" or "turnstile"\n captcha: {\n secretKey: process.env.RECAPTCHA_SECRET_KEY,\n },\n shouldValidate,\n }),\n ],\n }\n});`, `6997497713386314000`)\"\n >\n \n \n \n \n

import SuperTokens from 'supertokens-node';\nimport CaptchaPlugin, { ShouldValidate } from '@supertokens-plugins/captcha-nodejs';\n\n\n// Track failed attempts in memory (use Redis in production)\nconst failedLoginCache = new Map();\n\n\nfunction getFailedLoginCount(email) {\n  return failedLoginCache.get(email) || 0;\n}\n\n\nfunction incrementFailedLogin(email) {\n  const current = failedLoginCache.get(email) || 0;\n  failedLoginCache.set(email, current + 1);\n \n  // Expire after 1 hour\n  setTimeout(() => failedLoginCache.delete(email), 3600000);\n}\n\n\nconst shouldValidate: ShouldValidate = (api, input) => {\n  // Only require CAPTCHA for sign up\n  if (api === 'signUpPOST') {\n    return true;\n  }\n\n\n  // Check request headers for suspicious activity\n  if (api === 'signInPOST') {\n    const userAgent = input.options.req.getHeaderValue('user-agent');\n    if (!userAgent || userAgent.includes('bot')) {\n      return true;\n    }\n\n\n    // Optional: Check failed login history\n    const emailField = input.formFields?.find(f => f.id === 'email');\n    if (emailField) {\n      const failedCount = getFailedLoginCount(emailField.value);\n      if (failedCount >= 3) {\n        return true;\n      }\n    }\n\n\n    return false;\n  }\n\n\n  return false;\n};\n\n\nSuperTokens.init({\n  supertokens: {\n    connectionURI: '...',\n  },\n  appInfo: {\n    // your app info\n  },\n  recipeList: [\n    // your recipes\n  ],\n  experimental: {\n    plugins: [\n      CaptchaPlugin.init({\n        type: 'reCAPTCHAv3', // or \"reCAPTCHAv2\" or \"turnstile\"\n        captcha: {\n          secretKey: process.env.RECAPTCHA_SECRET_KEY,\n        },\n        shouldValidate,\n      }),\n    ],\n  }\n});
\n

This logic applies layered risk assessment:

\n
    \n
  • Always protect signup - Unconditional CAPTCHA for signUpPOST
    • \n
  • User agent inspection - Trigger CAPTCHA for missing or bot-like user agents
    • \n
  • Failed attempt history - Escalate to CAPTCHA after 3 failed login attempts
    • \n
  • API-specific policies - Different rules for different authentication endpoints
    • \n
\n

The validation logic remains isolated in the plugin configuration rather than scattered across authentication code. The input parameter provides access to request headers, form fields, and other context needed for risk assessment.

\n

Production Note: Replace the in-memory Map with Redis or another persistent cache to maintain state across server restarts and multiple instances.

\n

Frontend Conditional Rendering

\n

The frontend must coordinate with backend enforcement to display CAPTCHA widgets only when required. SuperTokens enables conditional rendering through custom input containers.

\n

For reCAPTCHA v2 with visible widgets or when you want precise control over which forms display CAPTCHA:

\n((props, ref) => {\n const { form, ...rest } = props;\n const { loadAndRender, containerId } = useCaptcha();\n\n\n useEffect(() => {\n // CAPTCHA applies/renders only for the EmailPasswordSignUpForm\n // and the EmailPasswordResetPasswordEmail\n if (\n form === 'EmailPasswordSignUpForm' ||\n form === 'EmailPasswordResetPasswordEmail'\n ) {\n loadAndRender();\n }\n }, [form]);\n\n\n return (\n
\n );\n});\n\n\nSuperTokens.init({\n appInfo: {\n // your app info\n },\n recipeList: [\n // your recipes\n ],\n experimental: {\n plugins: [\n CaptchaPlugin.init({\n type: 'reCAPTCHAv3', // or "reCAPTCHAv2" or "turnstile"\n captcha: {\n sitekey: 'your-site-key',\n },\n InputContainer: CaptchaInputContainer,\n }),\n ],\n }\n});`, `14227175720607410000`)\"\n >\n \n \n
\n \n
import { forwardRef, useEffect } from 'react';\nimport SuperTokens from 'supertokens-auth-react';\nimport CaptchaPlugin, {\n  CaptchInputContainerProps,\n  useCaptcha,\n} from '@supertokens-plugins/captcha-react';\n\n\nconst CaptchaInputContainer = forwardRef\n  HTMLDivElement,\n  CaptchInputContainerProps\n>((props, ref) => {\n  const { form, ...rest } = props;\n  const { loadAndRender, containerId } = useCaptcha();\n\n\n  useEffect(() => {\n    // CAPTCHA applies/renders only for the EmailPasswordSignUpForm\n    // and the EmailPasswordResetPasswordEmail\n    if (\n      form === 'EmailPasswordSignUpForm' ||\n      form === 'EmailPasswordResetPasswordEmail'\n    ) {\n      loadAndRender();\n    }\n  }, [form]);\n\n\n  return (\n    <div ref={ref} id={containerId} className=\"CAPTCHA-container\" {...rest} />\n  );\n});\n\n\nSuperTokens.init({\n  appInfo: {\n    // your app info\n  },\n  recipeList: [\n    // your recipes\n  ],\n  experimental: {\n    plugins: [\n      CaptchaPlugin.init({\n        type: 'reCAPTCHAv3', // or \"reCAPTCHAv2\" or \"turnstile\"\n        captcha: {\n          sitekey: 'your-site-key',\n        },\n        InputContainer: CaptchaInputContainer,\n      }),\n    ],\n  }\n});
\n

This configuration renders CAPTCHA widgets only on the signup form and password reset email form, matching common backend enforcement policies. The form prop identifies which form is currently being rendered, allowing precise control over CAPTCHA placement.

\n

Note: For reCAPTCHA v3 or Turnstile (both invisible), conditional rendering via InputContainer is optional since the widgets handle\nverification transparently in the background.

\n

Which CAPTCHA Provider Should I Use: reCAPTCHA, hCaptcha, or Turnstile?

\n

CAPTCHA provider selection involves balancing security effectiveness, user experience friction, privacy implications, and ecosystem\ncompatibility. Three major providers dominate the market, each with distinct characteristics.

\n

reCAPTCHA (Google)

\n

Strengths:

\n
    \n
  • The largest deployment base provides extensive training data for bot detection
    • \n
  • Invisible reCAPTCHA v3 scores requests without user interaction
    • \n
  • Deep integration with Google’s security infrastructure
    • \n
  • Comprehensive documentation and community support
    • \n
\n

Considerations:

\n
    \n
  • Data collection raises privacy concerns in some jurisdictions
    • \n
  • Google dependency may conflict with privacy policies or vendor diversification goals
    • \n
  • V2 checkbox challenges can frustrate users with accessibility needs
    • \n
\n

Use Cases:\nApplications prioritizing maximum bot detection accuracy and compatibility with existing Google infrastructure. Best suited for high-traffic services where Google’s data advantages deliver measurable value.

\n

hCaptcha

\n

Strengths:

\n
    \n
  • Privacy-focused alternative to reCAPTCHA with a GDPR compliance focus
    • \n
  • Pays website operators for solved CAPTCHA (machine learning data labeling business model)
    • \n
  • Accessible design with screen reader support
    • \n
  • No Google dependency for privacy-conscious deployments
    • \n
\n

Considerations:

\n
    \n
  • A smaller training dataset compared to reCAPTCHA may affect detection accuracy.
    • \n
  • Less widespread adoption results in fewer integration examples
    • \n
  • Challenge difficulty can vary based on training data requirements
    • \n
\n

Use Cases:\nApplications with strict privacy requirements, European deployments requiring GDPR compliance, or organizations seeking vendor diversification away from Google services.

\n

Turnstile (Cloudflare)

\n

Strengths:

\n
    \n
  • Minimal user friction with invisible background verification
    • \n
  • Privacy-first design with no personal data collection
    • \n
  • Free tier with generous limits
    • \n
  • Integration with Cloudflare’s broader security ecosystem
    • \n
\n

Considerations:

\n
    \n
  • Newer product with a smaller deployment history
    • \n
  • Effectiveness against sophisticated bots is still being validated at scale
    • \n
  • Requires a Cloudflare account even if not using other Cloudflare services
    • \n
\n

Use Cases:\nModern applications prioritize user experience and privacy. Ideal for Cloudflare customers who can leverage integrated security features. Best for deployments accepting newer technology in exchange for reduced friction.

\n

Provider Comparison

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FeaturereCAPTCHAhCaptchaTurnstile
User FrictionLow (v3) / Medium (v2)MediumVery Low
PrivacyLowerHigherHighest
AccuracyHighestHighDeveloping
AdoptionHighestGrowingEarly
CostFree (limits)Free (limits)Free (generous)
\n

SuperTokens Provider Flexibility

\n

SuperTokens maintains provider-agnostic CAPTCHA integration. The plugin interface abstracts provider-specific details, enabling swaps without refactoring authentication logic:

\n\n \n \n \n \n
// Switch from reCAPTCHA to Turnstile\nimport { Turnstile } from \"supertokens-auth-react/recipe/emailpassword/captcha\";\n\n\nEmailPassword.init({\n    captcha: Turnstile({\n        siteKey: \"YOUR_TURNSTILE_SITE_KEY\"\n    })\n});
\n

Backend configuration similarly accepts different providers through a consistent interface:

\n api === "signUpPOST"\n }\n});`, `9031015974848367000`)\"\n >\n \n \n \n \n
EmailPassword.init({\n    captcha: {\n        provider: \"turnstile\",\n        secretKey: process.env.TURNSTILE_SECRET_KEY,\n        shouldValidate: async (api) => api === \"signUpPOST\"\n    }\n});
\n

This abstraction protects authentication flows from provider churn. Switching CAPTCHA vendors requires updating the configuration, not\nrewriting the integration code.

\n

Can I Integrate CAPTCHA With SuperTokens Passwordless or Reset Flows?

\n

Bot protection extends beyond traditional username/password authentication. Passwordless flows, password reset mechanisms, and magic\nlink generation all present abuse vectors that benefit from CAPTCHA enforcement.

\n

Passwordless Code Generation

\n

Passwordless authentication sends one-time codes via email or SMS. Without protection, attackers can:

\n
    \n
  • Flood email/SMS services with code generation requests
    • \n
  • Exhaust rate limits and trigger service degradation
    • \n
  • Execute denial-of-service attacks targeting specific email addresses
    • \n
  • Generate costs through SMS provider billing
    • \n
\n

CAPTCHA on code generation endpoints prevents automated abuse while maintaining passwordless convenience.

\n

Password Reset Protection

\n

Password reset flows enable account takeover if insufficiently protected:

\n
    \n
  • Attackers enumerate valid email addresses by triggering reset emails
    • \n
  • Mass password reset requests overload email services
    • \n
  • Targeted reset requests harass specific users with spam
    • \n
\n

Requiring CAPTCHA before sending reset emails mitigates these vectors without weakening account recovery for legitimate users.

\n

SuperTokens Passwordless CAPTCHA

\n

SuperTokens applies CAPTCHA to passwordless flows through the same plugin mechanism:

\n {\n // Protect code creation\n if (api === "createCodePOST") {\n return true;\n }\n // Optionally protect code consumption\n if (api === "consumeCodePOST") {\n const failedAttempts = await getCodeFailureCount();\n return failedAttempts >= 3;\n }\n return false;\n }\n }\n});`, `42259988889161090000`)\"\n >\n \n \n \n \n
import Passwordless from \"supertokens-node/recipe/passwordless\";\n\n\nPasswordless.init({\n    contactMethod: \"EMAIL\",\n    captcha: {\n        secretKey: process.env.RECAPTCHA_SECRET_KEY,\n        shouldValidate: async (api) => {\n            // Protect code creation\n            if (api === \"createCodePOST\") {\n                return true;\n            }\n            // Optionally protect code consumption\n            if (api === \"consumeCodePOST\") {\n                const failedAttempts = await getCodeFailureCount();\n                return failedAttempts >= 3;\n            }\n            return false;\n        }\n    }\n});
\n

This configuration protects code generation unconditionally while applying conditional protection to code consumption based on failure\nhistory.

\n

Password Reset CAPTCHA

\n

Standard EmailPassword recipe supports CAPTCHA on reset flows:

\n {\n // Protect password reset token generation\n if (api === "generatePasswordResetTokenPOST") {\n return true;\n }\n // Optionally protect reset submission\n if (api === "passwordResetPOST") {\n return true;\n }\n return false;\n }\n }\n});`, `56228148413448030000`)\"\n >\n \n \n \n \n
EmailPassword.init({\n    captcha: {\n        secretKey: process.env.RECAPTCHA_SECRET_KEY,\n        shouldValidate: async (api) => {\n            // Protect password reset token generation\n            if (api === \"generatePasswordResetTokenPOST\") {\n                return true;\n            }\n            // Optionally protect reset submission\n            if (api === \"passwordResetPOST\") {\n                return true;\n            }\n            return false;\n        }\n    }\n});
\n

Protecting both token generation and reset submission provides defense in depth: CAPTCHA prevents automated token requests and validates human interaction when users submit new passwords.

\n

How Do I Configure Site Keys and Secret Keys for CAPTCHA?

\n

CAPTCHA providers issue two credentials that serve distinct roles in the verification flow:

\n

Site Key (Public)

\n

The site key identifies your application to the CAPTCHA provider and enables frontend widget loading. This key appears in client-side code, browser network traffic, and page source. Site keys are not sensitive; they merely identify which provider account handles verification requests.

\n

Secret Key (Private)

\n

The secret key authenticates backend verification requests to the provider’s API. This credential proves your backend’s authority to\nvalidate tokens. Secret keys must remain confidential; exposure enables attackers to bypass CAPTCHA by validating their own tokens.

\n

Obtaining Provider Keys

\n

reCAPTCHA:\nRegister at https://www.google.com/recaptcha/admin, create a site registration, and receive both the site key and the secret key.

\n

hCaptcha:\nCreate an account at https://dashboard.hcaptcha.com, add a new site, and obtain the sitekey and secret from settings.

\n

Turnstile:\nAccess Cloudflare dashboard at https://dash.cloudflare.com, navigate to Turnstile, create a site, and retrieve keys.

\n

Secure Storage Best Practices

\n

Secret keys require protection equivalent to database passwords or API tokens:

\n

Environment Variables:\nStore secret keys in environment variables, never hardcode in source files:

\n\n \n \n \n \n
# .env file (never committed to version control)\nRECAPTCHA_SECRET_KEY=YOUR_KEY\nTURNSTILE_SECRET_KEY=YOUR_KEY
\n

Load environment variables in your backend:

\n\n \n \n \n \n
import dotenv from \"dotenv\";\ndotenv.config();\nconst secretKey = process.env.RECAPTCHA_SECRET_KEY;
\n

For production, set environment variables through your hosting platform (Vercel, Netlify, Heroku, etc.).

\n

SuperTokens Configuration

\n

SuperTokens separates frontend and backend key configuration:

\n

Frontend (Site Key):

\n\n \n \n \n \n
import CaptchaPlugin from \"@supertokens-plugins/captcha-react\";\n\n\nSuperTokens.init({\n  experimental: {\n    plugins: [\n      CaptchaPlugin.init({\n        type: \"reCAPTCHAv3\",\n        captcha: {\n          sitekey: \"YOUR_SITE_KEY\", // Public site key\n        },\n      }),\n    ],\n  }\n});
\n

Backend (Secret Key):

\n\n \n \n \n \n
import CaptchaPlugin from \"@supertokens-plugins/captcha-nodejs\";\n\n\nSuperTokens.init({\n  experimental: {\n    plugins: [\n      CaptchaPlugin.init({\n        type: \"reCAPTCHAv3\",\n        captcha: {\n          secretKey: process.env.RECAPTCHA_SECRET_KEY, // From environment\n        },\n      }),\n    ],\n  }\n});
\n

This separation ensures secret keys remain server-side while frontend code receives only public credentials required for widget initialization.

\n

Conclusion

\n

Effective CAPTCHA use requires balancing security and user experience. Blanket enforcement blocks bots but often frustrates legitimate users, while risk-based enforcement maintains security with minimal friction.

\n

Server-side verification is mandatory. Client-side checks provide no real security, whereas backend validation with the provider’s secret key ensures the challenge was legitimately solved.

\n

SuperTokens’ plugin architecture keeps CAPTCHA logic separate from authentication, enabling selective enforcement, conditional triggers,\nand easy provider swaps through configuration rather than code changes. Teams should track false positives, false negatives, and user completion rates to continuously tune policies, minimize user impact, and avoid vendor lock-in.

","frontmatter":{"date":"December 26, 2025","title":"How Do I Add CAPTCHA to My Login Page?","cover":"captcha-supertokens.png","author":"Mostafa Ibrahim","description":" Learn how to add CAPTCHA to login and signup pages, protect your app from bots, and see how SuperTokens makes it simple."},"fields":{"slug":"/captcha-supertokens/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"5b44398d-fb89-5247-ab25-aa9ca8032444","fields__slug":"/captcha-supertokens/","__params":{"fields__slug":"captcha-supertokens"}}}, "staticQueryHashes": []}