User validation

SmartCaptcha runs user requests through its ML algorithms and challenges only users whose requests it finds 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 verifying the request, SmartCaptcha assigns it a unique identifier: a one-time token with a limited TTL. You can use this token to get the request’s verification result from the service.

After validation, the token is placed into an <input type="hidden" name="smart-token" value="<token>" ...> tag on the user’s page. For 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 tag containing the widget.
• value: Token value.

To obtain the verification result, send a POST request to https://smartcaptcha.cloud.yandex.ru/validate providing the following variables in x-www-form-urlencoded format:

secret=<server_key>&token=<token>&ip=<user_IP_address>

Where:

• secret: Server key.
• token: One-time token obtained after successful verification.
• ip: IP address of the user who sent the token verification request. Even though this argument is optional, we recommend that you include the user’s IP in your requests as it helps improve SmartCaptcha performance.

Service responseService response

The service will respond with a JSON object containing the status and message fields. If the status field is set to ok, the system adds the host field to the JSON object. This field indicates the website where the verification has been completed. For example:

1. It is a human. Verification has been completed on the example.com website:

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

2. It is a human. Verification has been completed on example.com via port 8080:

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

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

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

4. It is a robot:

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

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

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

Response processingResponse processing

To process responses correctly, refer to their status field:

• ok: Request processed successfully.
• failed: An error occurred.

There are two types of errors:

• This is a robot: "status": "failed", the message field is empty.
• Error in request: "status": "failed", the message field contains a description of the error.

Errors in the request may be due to an invalid token or a missing server key. We recommend that you detect and fix such errors during the development and testing step.

The message field is not for processing in code using conditions or comparisons. Use it for diagnostic purposes only.

Request errorsRequest errors

If your request to https://smartcaptcha.cloud.yandex.ru/validate is malformed, it will return an error. For example:

1. Request with no server key:

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

2. Request with a missing or corrupted token:

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

What's nextWhat's next

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