reCAPTCHA v3 API: Step-by-step Guide
Integrating reCAPTCHA v3 involves three sequential stages: registering your keys, wiring up the recaptcha v3 javascript on the frontend, and verifying the token on the backend. Here is the complete flow.
Step 1 — Register Your Keys in Google Admin Console
Before writing a single line of code, you need credentials.
- Go to the Google reCAPTCHA Admin Console.
- Fill in the Label name and select reCAPTCHA v3 (score-based, no challenge).
- Add all domains where your site runs (e.g., example.com, www.example.com).
- Select your Google Cloud Platform project, if present. If not, it will be created automatically.
- Submit the form. Google will provide two keys:
- Site key — public; used in your frontend HTML/JS.
- Secret key — private; used only on your backend server. Never expose it in client-side code.
Step 2 — Load the reCAPTCHA v3 JavaScript Library
On every page you want to protect, load the recaptcha v3 api script by adding the following tag to your HTML <head>, replacing YOUR_SITE_KEY with your actual key:
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
This single snippet initializes the recaptcha v3 google engine and begins passively collecting behavioral signals in the background — no widget is shown to the user.
Step 3 — Execute reCAPTCHA on a Protected Action
Unlike recaptcha v2, you do not render a widget. Instead, you call grecaptcha.execute() programmatically at the moment a user triggers a protected action.
Option A — Button with data-attributes (simple forms):
<form id="login-form">
<!-- your form fields -->
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-action="login"
type="button">
Log In
</button>
</form>
<script>
function onSubmit(token) {
fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
}
</script>
Option B — Programmatic execution (recommended for AJAX/API flows):
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
<script>
async function submitLogin() {
const token = await new Promise((resolve) => {
grecaptcha.ready(() => {
grecaptcha.execute("YOUR_SITE_KEY", { action: "login" }).then(resolve);
});
});
// Send token immediately -- it expires in 2 minutes
await fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
}
</script>
Key rule: The action name (e.g., login, signup, checkout) must match what your backend expects. This prevents token reuse across different endpoints.
Step 4 — Verify the Token on Your Backend
Your server receives the token and forwards it to Google's siteverify endpoint before processing the user's request.
Node.js example (with error handling):
import express from "express";
const app = express();
app.use(express.json());
app.post("/api/login", async (req, res) => {
const token = req.body.recaptchaToken;
const params = new URLSearchParams();
params.set("secret", process.env.RECAPTCHA_SECRET);
params.set("response", token);
let data;
try {
const verifyResp = await fetch("https://www.google.com/recaptcha/api/siteverify", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params
});
data = await verifyResp.json();
} catch (err) {
console.error("reCAPTCHA verification network error:", err);
return res.status(503).json({ error: "verification_unavailable" });
}
// → proceed to Step 5
});
Note: Native fetch is available in Node.js 18+. For older versions, use node-fetch or axios.
Python (Flask ≥ 2.0) example:
import os, requests
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/api/signup") # Requires Flask >= 2.0
def signup():
token = request.json.get("recaptchaToken")
resp = requests.post(
"https://www.google.com/recaptcha/api/siteverify",
data={"secret": os.environ["RECAPTCHA_SECRET"], "response": token},
timeout=5
)
data = resp.json()
# → proceed to Step 5
if not data.get("success"):
return jsonify({"error": "recaptcha_failed"}), 403
return jsonify({"ok": True})
Step 5 — Interpret the Score and Act
Google's siteverify endpoint returns a JSON response. Here is what a successful response looks like:
{
"success": true,
"score": 0.7,
"action": "login",
"challenge_ts": "2026-02-27T10:00:00Z",
"hostname": "example.com"
}
Your backend must check three things in order:
- success is true— the token is valid and was accepted by Google.
- action matches your expected value — confirms the token was generated for the right context.
- score meets your threshold — 0.5 is Google's recommended starting point.
Step 6 — Handle Errors Gracefully
The siteverify response may include an error-codes array. The most important ones to handle are:
- timeout-or-duplicate — the token is older than 2 minutes or was already used; re-run grecaptcha.execute() client-side to get a fresh token.
- missing-input-secret / invalid-input-secret — your secret key is missing or incorrect; a configuration bug, not a user error.
- missing-input-response / invalid-input-response — the token was not sent or is malformed; check your frontend integration.
- bad-request — the overall request to siteverify is malformed.
Never surface raw error codes to end users — log them server-side and show a generic "please try again" message.
Step 7 — Test Your Integration End-to-End
Before going to production, verify the full flow:
- Open your protected page, trigger the action, and confirm a token is generated in the browser.
- Log the raw siteverify response on the backend to confirm success: true, a valid score, and the correct action.
- For automated testing, CapMonster Cloud provides a solver API that generates valid reCAPTCHA v3 tokens programmatically. It supports reCAPTCHA v3, v2, and Enterprise and integrates via a REST API.
- Confirm your error-handling paths work by sending an expired or malformed token and checking that your backend returns the correct response.
Privacy and Compliance Considerations
reCAPTCHA version 3's behavioral profiling model comes with meaningful privacy implications. The system collects mouse movements, keystroke timing, browser fingerprints, IP addresses, and more — data that goes well beyond what is strictly necessary to verify humanness.
For European operators in particular, this creates GDPR exposure. In a notable 2023 enforcement action, the French data protection authority (CNIL) fined e-scooter company Cityscoot €125,000 for multiple GDPR violations — including both collecting excessive geolocation data (tracking scooters every 30 seconds) and deploying Google reCAPTCHA without proper user consent. CNIL ruled that reCAPTCHA's access to user terminal data requires prior consent under Article 82 of the French Data Protection Act — not just a passive security widget. If you operate under GDPR, implementing a proper Data Processing Agreement with Google and obtaining appropriate user consent is essential before deploying google recaptcha v3.
CapMonster Cloud and reCAPTCHA v3
CapMonster Cloud is an AI-powered CAPTCHA recognition and automation service that supports reCAPTCHA v2, v3, and Enterprise, among many other CAPTCHA types. For development and testing teams, it provides a way to automate interactions with reCAPTCHA-protected forms without manual intervention — useful for integration testing, automated monitoring pipelines, or legitimate scraping workflows where CAPTCHA handling is a bottleneck.
In the context of using recaptcha v3, CapMonster Cloud functions as a solver API: given a target URL and site key, it returns a valid reCAPTCHA token that can be submitted to the protected endpoint just as a real browser would.
Example of solving reCAPTCHA v3 using CapMonster Cloud:
Create task:
POST
https://api.capmonster.cloud/createTask
Request
{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
"websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
"isEnterprise": false,
"minScore": 0.7,
"pageAction": "myverify"
}
}
Response
{
"errorId":0,
"taskId":407533072
}
Get task result:
POST
https://api.capmonster.cloud/getTaskResult
Request
{
"clientKey":"API_KEY",
"taskId": 407533072
}
Response
{
"errorId":0,
"status":"ready",
"solution": {
"gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3"
}
}
Detailed API documentation and integration examples are available at capmonster.cloud.
Conclusion
reCAPTCHA v3 represents a meaningful step forward in balancing bot protection with user experience. By moving verification entirely into the background and replacing binary pass/fail logic with a nuanced risk score, recaptcha google v3 lets security teams act proportionally — blocking clear bots, stepping up friction for suspicious sessions, and leaving legitimate users completely undisturbed.
The trade-offs are real: score interpretation requires backend investment, threshold tuning takes time, and the privacy footprint is non-trivial under GDPR. But for most production web applications — especially those where friction at login, signup, or checkout costs conversions — the upgrade from v2 is well worth it.
Ready to implement reCAPTCHA v3 on your site — or automate your testing pipeline around it? Visit CapMonster Cloud to explore AI-powered CAPTCHA solving for reCAPTCHA v3, v2, and Enterprise — with full API documentation and integration examples to get you started in minutes.