Yandex Cloud
Search
Contact UsTry it for free
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
  • Marketplace
    • Featured
    • Infrastructure & Network
    • Data Platform
    • AI for business
    • Security
    • DevOps tools
    • Serverless
    • Monitoring & Resources
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Center for Technologies and Society
    • Yandex Cloud Partner program
    • Price calculator
    • Pricing plans
  • Customer Stories
  • Documentation
  • Blog
© 2026 Direct Cursus Technology L.L.C.
Yandex SmartCaptcha
  • Getting started
  • Access management
  • Pricing policy
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes

In this article:

  • Getting started
  • Create a CAPTCHA
  • Retrieve the CAPTCHA keys
  • Add the widget to the page
  • Check the user response
  • FAQ
  • Useful links

Getting started with Yandex SmartCaptcha

Written by
Yandex Cloud
Updated at March 19, 2026
  • Getting started
  • Create a CAPTCHA
  • Retrieve the CAPTCHA keys
  • Add the widget to the page
  • Check the user response
  • FAQ
  • Useful links

Yandex SmartCaptcha: Service for protection against bots and automated attacks.

To add a CAPTCHA to your HTML page:

  1. Create a CAPTCHA in Yandex Cloud.
  2. Copy keys from the CAPTCHA info page.
  3. Add the CAPTCHA widget code to your HTML page.
  4. 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 startedGetting started

  1. Navigate to the management console. Log in to Yandex Cloud or register if you do not have an account yet.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and its status is ACTIVE or TRIAL_ACTIVE. If you do not have a billing account, create one.

Create a CAPTCHACreate 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 when creating a CAPTCHA or later in its settings.

Management console
  1. In the management console, select a folder.

  2. Go to SmartCaptcha.

  3. Click Create captcha.

  4. Enter a name for the CAPTCHA, e.g., sm-captcha.

  5. List the sites the CAPTCHA will be on, e.g., my-shop.com.

  6. Do not edit the Style field.

  7. Select the default CAPTCHA settings (or leave the current ones):

    1. Main challenge: The challenge the user will see first.
    2. 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.
    3. 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.

    step9-10

  8. Click Create.

Retrieve the CAPTCHA keysRetrieve the CAPTCHA keys

Management console

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.

step4-get-keys

Add the widget to the pageAdd the widget to the page

Add the widget automatically:

  1. 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.js script will automatically find all div elements with the smart-captcha class and install the widget in them.

  2. Add an empty container (div element) 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 the 100px container 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 responseCheck 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
Node.js
PHP
Python
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, ok or failed. If successful, the service adds the host field 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.

FAQFAQ

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?

See Advanced widget settings.

What should I do if a CAPTCHA does not appear?

Make sure the domain is listed among the allowed websites in the CAPTCHA settings.

Useful linksUseful links

  • Widget rendering methods
  • Style customization options
  • API Reference

Was the article helpful?

Next
All guides
© 2026 Direct Cursus Technology L.L.C.