User validation

SmartCaptcha checks user requests with its ML algorithms and only shows challenges to those users whose requests it considers suspicious.

You do not have to place the "I’m not a robot" button on the page.

Standard CAPTCHAStandard CAPTCHA

Standard CAPTCHA is a way to connect the SmartCaptcha widget with the "I’m not a robot" button, which sends the user's request to SmartCaptcha. If the service finds the request suspicious, it will prompt the user to complete a challenge.

Invisible CAPTCHAInvisible CAPTCHA

Invisible CAPTCHA is a way of connecting the SmartCaptcha widget without the I’m not a robot button on the page. Only users whose requests are considered suspicious by the service will see the challenge window.

It is the developer who decides which event should trigger the service to check the user.

Validation resultValidation result

After validating a request, SmartCaptcha assigns it an ID: a one-time token. You can use the token to retrieve the result of a user request validation from the service. The token is valid for five minutes. After this time expires, it becomes invalid and the user has to go through the validation process again.

After validation, the token is loaded into the <input type="hidden" name="smart-token" value="<token>" ...> element on the user page. Here is an example:

<div id="captcha-container" class="smart-captcha" ...>
    <input type="hidden" name="smart-token" value="dD0xNjYyNDU3NDMzO2k9MmEwMjo2Yjg6YjA4MTpiNTk3OjoxOjFiO0Q9MjVCREY1RDgzMDBERjQ3QjExNkUyMDJDNjJFNEI3Q0Y0QjYzRkRDNzJEMkV********DNjMxODgzMUM0REZBNzI1QUE1QzUwO3U9MTY2MjQ1NzQzMzk5MTEwNjQxNTtoPTg4MWRjMDc2YzE3MjkxNGUwNDgwMTVkYzhl********">
    ...
</div>

Where:

• <div id="captcha-container" class="smart-captcha" ...>: div element with a widget.
• value: Token value.

To find out the result of the validation, send a POST request to https://smartcaptcha.yandexcloud.net/validate providing 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.

Service responseService response

In its response, the service will return a JSON object containing the status and message fields. If the status field value is ok, the host field is added to the JSON object. It shows on what website the validation was passed. For example:

1. It is a human. User validation was passed on the example.com website:

   {
       "status": "ok",
       "message": "",
       "host": "example.com"
   }
   

2. It is a human. User validation was passed on the example.com website via port 8080:

   {
       "status": "ok",
       "message": "",
       "host": "example.com:8080"
   }
   

3. Empty host field. This may indicate that the cloud is blocked or an internal service failure occurred:

   {
       "status": "ok",
       "message": "",
       "host": ""
   }
   

4. It is a robot:

   {
       "status": "failed",
       "message": ""
   }
   

5. Request with a fake or damaged token. It is a robot:

   {
       "status": "failed",
       "message": "Token invalid or expired."
   }
   

Request errorsRequest errors

If your request to https://smartcaptcha.yandexcloud.net/validate is incorrect, the service will return an error. Here is an example:

1. Request missing the server key:

   {
       "status": "failed",
       "message": "Authentication failed. Secret has not provided."
   }
   

2. Request with a missing or damaged token:

   {
       "status": "failed",
       "message": "Token invalid or expired."
   }
   

What's nextWhat's next

• How to connect an invisible CAPTCHA.
• CAPTCHA in React.