Getting started with Yandex SmartCaptcha
Yandex SmartCaptcha: Service for protection against bots and automated attacks.
To add a CAPTCHA to your HTML page:
- Create a CAPTCHA in Yandex Cloud.
- Copy keys from the CAPTCHA info page.
- Add the CAPTCHA widget code to your HTML page.
- Check the user's response by sending a POST request.
If having problems configuring SmartCaptcha:
- For the Business and Premium support plans, contact support
. - In other cases, contact your account manager to get you in touch with their support team.
Getting started
- Navigate to the management console
. Log in to Yandex Cloud or register if you do not have an account yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and its status isACTIVEorTRIAL_ACTIVE. If you do not have a billing account, create one.
Create a CAPTCHA
Note
To enhance your security, we use HTTP request data to improve our machine learning (ML) models. You can disable the use of this information in the management console
-
In the management console
, select a folder. -
Go to SmartCaptcha.
-
Click Create captcha.
-
Enter a name for the CAPTCHA, e.g.,
sm-captcha. -
List the sites the CAPTCHA will be on, e.g.,
my-shop.com. -
Do not edit the Style field.
-
Select the default CAPTCHA settings (or leave the current ones):
- Main challenge: The challenge the user will see first.
- Additional challenge: The challenge the user will be offered if the service finds the results of the main one suspicious, or if the CAPTCHA is at maximum difficulty.
- Select the difficulty level,
Medium.
You can add challenge options and configure incoming traffic rules to show different CAPTCHAs to different users. In this example, you will configure a single default CAPTCHA for all users.

-
Click Create.
Retrieve the CAPTCHA keys
After creating a CAPTCHA, select it from the list and copy the two keys:
- Client key: To add a SmartCaptcha widget to the your website or HTML page.
- Server key: To check the user response.
Store them in a secure place.

Add the widget to the page
Add the widget automatically:
-
Add the JS script to your HTML page. To do this, place the following code anywhere on the page, e.g., inside the
<head>tag:<script src="https://smartcaptcha.cloud.yandex.ru/captcha.js" defer></script>The
captcha.jsscript will automatically find alldivelements with thesmart-captchaclass and install the widget in them. -
Add an empty container (
divelement) for the CAPTCHA widget to the page:<div id="captcha-container" class="smart-captcha" data-sitekey="<client_key>" ></div>Where
<client_key>is the key you copied after creating the CAPTCHA.Note
During the upload, the widget changes the height of its host container to
100px. This might result in an undesirable layout shift on the page due to the height change. To avoid this shift, set the100pxcontainer height before the widget is loaded.<div ... style="height: 100px"></div>
The I’m not a robot button will appear on the page. When a user clicks the button, SmartCaptcha will validate their request.
If the request seems suspicious, SmartCaptcha will ask the user to solve a CAPTCHA challenge.
Check the user response
After the CAPTCHA verification, the user is issued a unique token placed into the CAPTCHA widget container on the HTML page as <input>:
<div id="captcha-container" class="smart-captcha" ...>
<input type="hidden" name="smart-token" value="<token>">
...
</div>
To validate the token, send a POST request to https://smartcaptcha.cloud.yandex.ru/validate providing the following parameters in x-www-form-urlencoded format:
secret=<server_key>&token=<token>&ip=<user_IP_address>
Where:
secret: Server key.token: One-time token received after passing the check.ip: IP address of the user that originated the request to validate the token. This is an optional parameter, but we ask you to provide the user IP when making requests. This helps improve SmartCaptcha performance.
Example of the token validation function:
curl -X POST https://smartcaptcha.cloud.yandex.ru/validate \
-d "secret=<server_key>" \
-d "token=<token_from_form>" \
-d "ip=<user_IP_address>"
const https = require('https'),
querystring = require('querystring');
const SMARTCAPTCHA_SERVER_KEY = "<server_key>";
function check_captcha(token, callback) {
const postData = querystring.stringify({
secret: SMARTCAPTCHA_SERVER_KEY,
token: token,
ip: '<user_IP_address>', // Method for retrieving the user IP address depends on your framework and proxy.
});
const options = {
hostname: 'smartcaptcha.cloud.yandex.ru',
port: 443,
path: '/validate',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Content-Length': Buffer.byteLength(postData),
},
};
const req = https.request(options, (res) => {
let content = '';
res.on('data', (chunk) => {
content += chunk;
});
res.on('end', () => {
if (res.statusCode !== 200) {
console.error(`Allow access due to an error: code=${res.statusCode}; message=${content}`);
callback(true);
return;
}
try {
const parsedContent = JSON.parse(content);
callback(parsedContent.status === 'ok');
} catch (err) {
console.error('Error parsing response: ', err);
callback(true);
}
});
});
req.on('error', (error) => {
console.error(error);
callback(true);
});
// Writing the POST data to the request body
req.write(postData);
req.end();
}
let token = "<token>";
check_captcha(token, (passed) => {
if (passed) {
console.log("Passed");
} else {
console.log("Robot");
}
});
define('SMARTCAPTCHA_SERVER_KEY', '<server_key>');
function check_captcha($token) {
$ch = curl_init("https://smartcaptcha.cloud.yandex.ru/validate");
$args = [
"secret" => SMARTCAPTCHA_SERVER_KEY,
"token" => $token,
"ip" => "<user_IP_address>", // You need to provide the user IP address.
// Method for retrieving the user IP depends on your proxy.
];
curl_setopt($ch, CURLOPT_TIMEOUT, 1);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($args));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpcode !== 200) {
echo "Allow access due to an error: code=$httpcode; message=$server_output\n";
return true;
}
$resp = json_decode($server_output);
return $resp->status === "ok";
}
$token = "<token>"; // For example, $_POST['smart-token'];
if (check_captcha($token)) {
echo "Passed\n";
} else {
echo "Robot\n";
}
import requests
import sys
import json
SMARTCAPTCHA_SERVER_KEY = "<server_key>"
def check_captcha(token):
resp = requests.post(
"https://smartcaptcha.cloud.yandex.ru/validate",
data={
"secret": SMARTCAPTCHA_SERVER_KEY,
"token": token,
"ip": "<user_IP_address>" # Method for retrieving the IP address depends on your framework and proxy.
# In Flask, for example, this can be `request.remote_addr`
},
timeout=1
)
server_output = resp.content.decode()
if resp.status_code != 200:
print(f"Allow access due to an error: code={resp.status_code}; message={server_output}", file=sys.stderr)
return True
return json.loads(server_output)["status"] == "ok"
token = "<token>" # For example, request.form["smart-token"]
if check_captcha(token):
print("Passed")
else:
print("Robot")
In its response, the service will return a JSON object containing the following fields:
status: Validation result,okorfailed. If successful, the service adds thehostfield to the JSON object which represents the website where the check was.message: Validation message, e.g.,Token invalid or expired.
For response examples, see User validation.
FAQ
How do I test CAPTCHA?
Open the CAPTCHA page in incognito mode or use a VPN to increase the chance of getting a challenge.
How do I customize the CAPTCHA appearance?
What should I do if a CAPTCHA does not appear?
Make sure the domain is listed among the allowed websites in the CAPTCHA settings.