CapMonster Cloud API
Extension for browsers
In this article, we have tried to answer all the key questions. The first step in solving the task is to determine which protection system is being used. To do this, you can refer to the list of popular captchas and anti-bot protection systems, where you will find visual examples and key indicators that help you quickly understand what you are dealing with.
If you discover that your site uses reCAPTCHA v2 Enterprise, the next step is to study its properties and operation in more detail. In this article, you can also review the instructions on how to integrate reCAPTCHA v2 Enterprise so that you fully understand how it functions on your site. This will help you not only understand the current protection, but also properly plan its maintenance.
When testing forms that include reCAPTCHA v2 Enterprise, you often need to verify that the captcha works and is integrated correctly.
You can verify the captcha embedded on your site manually.
For automatic solving you can use tools like CapMonster Cloud, which accepts captcha parameters, processes them on its servers, and returns a ready-to-use token. Insert this token into the form to pass the check without user interaction.
Working with CapMonster Cloud via API typically involves the following steps:
Creating a task
Sending an API requestYour request to solve reCAPTCHA v2 Enterprise must include:
type - RecaptchaV2EnterpriseTask;
websiteURL - the page address where the captcha appears;
websiteKey - the site key (sitekey) shown on that page;
enterprisePayload - provide this if your reCAPTCHA Enterprise widget passes an extra s field inside the object sent to grecaptcha.enterprise.render together with the sitekey;
pageAction - the action value your widget sends to Google. Default: verify.
https://api.capmonster.cloud/createTask{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTask",
"websiteURL": "https://mydomain.com/page-with-recaptcha-enterprise",
"websiteKey": "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
"pageAction": "verify",
"enterprisePayload": {
"s": "SOME_ADDITIONAL_TOKEN"
}
}
}
{
"errorId":0,
"taskId":407533072
}
Receiving the resulthttps://api.capmonster.cloud/getTaskResult{
"clientKey":"API_KEY",
"taskId": 407533072
}
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AFcWeA66ZARdA5te7acD9vSwWE2hEQ2-B2aqFxm455iMA-g-Jis..."
}
}
Placing the token on the pageimport { chromium } from 'playwright';
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2EnterpriseRequest } from '@zennolab_com/capmonstercloud-client';
(async () => {
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();
// 2. Open the page with the captcha
await page.goto('https://example.com');
// 3. Create a CapMonster Cloud client
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: '<your_capmonster_cloud_api_key>' })
);
// 4. Configure the request that solves the captcha
const recaptchaRequest = new RecaptchaV2EnterpriseRequest({
websiteURL: page.url(),
websiteKey: '6Lf76sUnAAAAAIKLuWNyegRsFUfmI-3Lex3xT5N'
// enterprisePayload: { s: 'SOME_ADDITIONAL_TOKEN' } // Optional enterprise parameter
});
// 5. Solve the captcha via CapMonster
const solution = await cmcClient.Solve(recaptchaRequest);
const token = solution.solution.gRecaptchaResponse;
console.log('Captcha token:', token);
// 6. Insert the token into a hidden field
await page.evaluate((t) => {
const el = document.getElementById('g-recaptcha-response');
if (el) el.value = t;
}, token);
// 7. (Optional) Submit the form — replace with the selector you need
await page.click('button[data-action="submit"]');
await page.waitForTimeout(5000);
await browser.close();
})();Because reCAPTCHA Enterprise runs on Google Cloud, you must create a project in its console first:
1. Go to Google Cloud Console.
2. In the top menu, choose an existing project or click New project.
3. Enter a project name, specify your organization, and confirm the creation.
4. Open the API page: reCAPTCHA Enterprise API, and click Enable.
5. Go to Create key in the console and click Create Key.
6. Configure the basic settings:
Next, open Additional Settings, toggle Will you use challenges?, and enable Checkbox Challenge.
7. Click Create. You’ll receive a key that must be added to your site to activate the protection.
8. Add the script to your page.
Sample HTML snippet you can embed on your site<html>
<head>
<title>reCAPTCHA demo: Simple page</title>
<script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<div class="g-recaptcha" data-sitekey="YOUR_SITEKEY" data-action="LOGIN"></div>
<br/>
<input type="submit" value="Submit">
</form>
</body>
</html>9. Validate the response on the server
PHP exampleThe token (g-recaptcha-response) is sent to the backend.
It is valid for 2 minutes, so verify it as soon as you receive it! For secure communication with the API, we recommend the official Google Cloud libraries:
<?php
require 'vendor/autoload.php';
// Install the Google Cloud libraries via Composer
use Google/Cloud/RecaptchaEnterprise/V1/RecaptchaEnterpriseServiceClient;
use Google/Cloud/RecaptchaEnterprise/V1/Event;
use Google/Cloud/RecaptchaEnterprise/V1/Assessment;
use Google/Cloud/RecaptchaEnterprise/V1/CreateAssessmentRequest;
use Google/Cloud/RecaptchaEnterprise/V1/TokenProperties/InvalidReason;
/**
* Validate the reCAPTCHA Enterprise token and obtain the risk score.
*
* @param string $recaptchaKey Your site/app reCAPTCHA key
* @param string $token Token received from the client
* @param string $projectId Google Cloud project ID
* @param string $action Action name associated with the token
*/
function create_assessment(string $recaptchaKey, string $token, string $projectId, string $action): void {
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($projectId);
// Create the assessment event
$event = (new Event())->setSiteKey($recaptchaKey)->setToken($token);
$assessment = (new Assessment())->setEvent($event);
$request = (new CreateAssessmentRequest())->setParent($projectName)->setAssessment($assessment);
try {
$response = $client->createAssessment($request);
if (!$response->getTokenProperties()->getValid()) {
echo 'Token is invalid: ' . InvalidReason::name($response->getTokenProperties()->getInvalidReason());
return;
}
if ($response->getTokenProperties()->getAction() === $action) {
echo 'Risk score: ' . $response->getRiskAnalysis()->getScore();
} else {
echo 'The action in the reCAPTCHA tag doesn’t match the expected value';
}
} catch (Exception $e) {
echo 'Error while checking reCAPTCHA: ' . $e->getMessage();
}
}
// Call the function with the variables
create_assessment(
'YOUR_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_PROJECT_ID',
'YOUR_RECAPTCHA_ACTION'
);
?>
If you’ve taken over a website that already has a captcha or another protection system installed, but you don’t have access to the code, don’t worry! It’s quite easy to identify which technology is being used. To verify that everything works correctly, you can use the CapMonster Cloud recognition service in an isolated test environment to make sure that the token processing mechanism and the validation logic are functioning properly.
In the case of reCAPTCHA v2 Enterprise, it’s enough to detect the system, observe its behavior, and confirm that the protection is working correctly. In this article, we showed how to identify reCAPTCHA v2 Enterprise and where to find instructions on how to integrate or reconfigure it, so you can confidently maintain the protection and keep its operation under control.
