Creating a CAPTCHA

Written by

Updated at April 17, 2025

SmartCaptcha allows you to create CAPTCHAs of multiple difficulty levels for various incoming requests. The difficulty level is determined by the basic properties of the incoming traffic.

When creating a CAPTCHA, you can:

Connect a CAPTCHA to multiple websites.
Set up the CAPTCHA appearance, such as background, states, errors, and the I'm not a robot button style.
Select the type and difficulty level of a CAPTCHA challenge.
Show various CAPTCHA options based on the incoming request properties, such as use different CAPTCHA for the users from different countries.

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

CLI

Terraform

API

In the management console, select the folder.
Select SmartCaptcha.
Click Create captcha.
Specify the Name of the CAPTCHA you are creating:
- It must be 2 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter, the last one cannot be a hyphen.
Optionally, select Disable domain check.
Specify Host list as IP addresses or domain names without http/https or/ at the end, e.g., example.com.

The CAPTCHA will also be valid for all subdomains of the specified domain names.
Set up the Style of the I'm not a robot button and the challenge window:
- Standard: Default appearance
- Gray
- Dark theme
- Blue
Under Сustomize style, you can set custom properties for the challenge window and other elements through the form or style description in JSON format.

All changes will be displayed in the preview window.
Configure the Challenge options. You can only specify the default CAPTCHA or add other options if you want to show different CAPTCHAs for different requests.
For the Default option, specify:
- Main challenge: Type of the main challenge the user will get.
- Additional challenge: Type of the additional challenge the user will get.
- Complexity: Difficulty level of the challenge the user will get:
- Easy: Simple challenge.
- Medium: Medium level challenge.
- Hard: Difficult challenge.
- Maximum: Difficult challenge with an additional question. The user is required to solve an additional challenge, regardless of the results of the main one.
  
  You can see a sample challenge in the preview window.
  
  Note
  
  The feature of challenge options and show rules is at the Preview stage.
To show different CAPTCHAs for different requests:
1. Click Add option and configure the settings as you would do for default CAPTCHA.
  
  To delete an option, click . If an option is used in the show rule, you cannot delete it.
2. Add the rules for incoming traffic that will determine which CAPTCHA option to show:
  - Click Add rule.
  - Specify the rule name and description.
  - Select a CAPTCHA option.
  - Specify the rule priority from 1 to 999999.
    
    Rules are checked in the ascending priority order, starting from 1, 2, etc. If the traffic matches multiple rules, the first rule to trigger will apply.
  - Specify one or more conditions for the incoming traffic:
    - IP: IP address, IP address range, or IP address region.
    - HTTP header: HTTP header string.
    - URI: Path of the incoming request to the website.
    - Host: Domain receiving the request.
  - Click Add.
    
    To delete a rule, click . You cannot delete a default rule.
3. Add other CAPTCHA options and rules for incoming traffic in a similar way.
Optionally, enable or disable the use of HTTP request information to improve machine learning models under Fine-tuning ML models.
Click Create.

The CAPTCHA will appear on the service page under Captcha list.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameters.

View the description of the CLI command for creating a CAPTCHA:
```
yc smartcaptcha captcha create --help
```
Create a CAPTCHA:
```
yc smartcaptcha captcha create \
  --name <captcha_name>
  --turn-off-hostname-check \
  --allowed-site <first_host>,<second_host> \
  --style-json '<captcha_appearance>' \
  --pre-check-type <main_challenge_type> \
  --challenge-type <additional_challenge_type> \
  --complexity <challenge_difficulty> \
  --override-variants-file <path_to_file_with_rules>.yaml \
  --security-rules-file <path_to_file_with_options>.yaml
```
Where:
- --name: CAPTCHA name.
- --turn-off-hostname-check: Disable domain check. This is an optional parameter.
- --allowed-site: List of hosts as IP addresses or domain names. without http/https or / at the end, e.g., example.com. The CAPTCHA will also be valid for all subdomains of the specified domain names. This is an optional parameter.
- --style-json: Appearance of the challenge window and other elements, in JSON format. For more details, see the JSON generated using the management console. This is an optional parameter.
- --pre-check-type: Type of the default main challenge the user will get.
- --challenge-type: Type of the default additional challenge the user will get.
- --complexity: Default challenge difficulty. The possible values are:
  - EASY: Simple challenge.
  - MEDIUM: Medium level challenge.
  - HARD: Difficult challenge.
  - FORCE_HARD: Difficult challenge with an additional question. The user is required to solve an additional challenge, regardless of the results of the main one.
  Note
  
  The feature of challenge options and show rules is at the Preview stage.
- --security-rules-file: Path to a YAML file containing the rules for incoming traffic that will determine which CAPTCHA option to show. This is an optional parameter.
  Example of a file with rules for incoming traffic
  - name: <rule_1_name> priority: "<rule_1_priority>" description: <rule_1_description> override_variant_uuid: <challenge_variant_ID> condition: host: hosts: - exact_match: example.com - exact_match: example.net - name: <rule_2_name> priority: "<rule_2_priority>" description: <rule_2_description> override_variant_uuid: <challenge_variant_ID> condition: source_ip: geo_ip_match: locations: - ru - es
  Where:
  - name: Rule name.
  - priority: Rule priority, from 1 to 999999.
    
    Rules are checked in the ascending priority order, starting from 1, 2, etc. If traffic matches multiple rules, the first rule to trigger will apply.
  - description: Rule description. This is an optional parameter.
  - override_variant_uuid: ID of the challenge option to show if the traffic matches the rule. If the parameter is not specified, the user will get the default challenge.
  - condition: One or more conditions for the incoming traffic. This is an optional parameter.
- --override-variants-file: Path to a YAML file with challenge options. This is an optional parameter.
  Example of a file with challenge options
  - uuid: <option_1_ID> description: <option_1_description> complexity: <challenge_difficulty> pre_check_type: <main_challenge> challenge_type: <additional_challenge> - uuid: <option_2_ID> description: <option_2_description> complexity: <challenge_difficulty> pre_check_type: <main_challenge> challenge_type: <additional_challenge>
  Where:
  - uuid: Unique ID of the challenge option.
  - description: Challenge option description.
  - complexity: Difficulty level of the challenge the user will get.
  - pre_check_type: Type of the main challenge the user will get.
  - challenge_type: Type of the additional challenge the user will get.

Result:

id: bpnd6cm6qpr5********
folder_id: b1g0ijbfaqsn********
cloud_id: b1gia87mbaom********
client_key: ysc1_2lla0Yn6dhlnEaTv2QNg2BhuA8Nqlyk4L7pZk3dz********
created_at: "2025-03-02T21:38:48.830498Z"
name: my-first-captcha
allowed_sites:
  - exmaple.com
  - exmaple.net
complexity: MEDIUM
style_json: '{"focus-color":"rgb(250, 192, 0)","base-background-color":"#fff"}'
turn_off_hostname_check: true
pre_check_type: CHECKBOX
challenge_type: IMAGE_TEXT
security_rules:
  - name: rule1
    priority: "11"
    description: My first security rule.
    condition:
      host:
        hosts:
          - exact_match: example.com
          - exact_match: example.net
    override_variant_uuid: variant-1
  - name: rule2
    priority: "12"
    condition:
      source_ip:
      geo_ip_match:
        locations:
          - ru
          - es
    override_variant_uuid: variant-2
override_variants:
  - uuid: variant-1
    description: override variant 1
    complexity: EASY
    pre_check_type: CHECKBOX
    challenge_type: SILHOUETTES
  - uuid: variant-2
    description: override variant 2
    complexity: HARD
    pre_check_type: CHECKBOX
    challenge_type: KALEIDOSCOPE

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the documentation on the Terraform website or mirror website.

If you don't have Terraform, install it and configure the Yandex Cloud provider.

To create a CAPTCHA:

In the Terraform configuration file, define the parameters of the resources you want to create:
```
resource "yandex_smartcaptcha_captcha" "demo-advanced-smartcaptcha" {
  name                = "<captcha_name>"
  style_json          = "<captcha_appearance>"
  complexity          = "<challenge_difficulty>"
  pre_check_type      = "<main_challenge_type>"
  challenge_type      = "<additional_challenge_type>"

  allowed_sites = [
    "<first_host>",
    "<second_host>"
  ]

  # First challenge variant
  override_variant {
    uuid        = "<variant_1_ID>"
    description = "<variant_1_description>"

    complexity     = "<challenge_difficulty>"
    pre_check_type = "<main_challenge>"
    challenge_type = "<additional_challenge>"
  }

  # Second challenge variant 
  override_variant {
    uuid        = "<variant_2_ID"
    description = "<variant_2_description>"

    complexity     = "<challenge_difficulty>"
    pre_check_type = "<main_challenge>"
    challenge_type = "<additional_challenge>"
  }

  # First rule
  security_rule {
    name                  = "<rule_1_name>"
    priority              = <rule_1_priority>
    description           = "<rule_1_description>"
    override_variant_uuid = "<challenge_variant_ID>"

    condition {
      host {
        hosts {
          exact_match = "example.com"
        }
        hosts {
          exact_match = "example.net"
        }
      }
    }
  }

  # Second rule
  security_rule {
    name                  = "<rule_2_name>"
    priority              = <rule_2_priority>
    description           = "<rule_2_description>"
    override_variant_uuid = "<challenge_variant_ID>"

    condition {
      source_ip {
        geo_ip_match {
          locations = ["ru", "es"]
        }
      }
    }
  }
}
```
Where:
- name: CAPTCHA name.
- style_json: Appearance of the challenge window and other elements, in JSON format. For more details, see the JSON generated using the management console. This is an optional parameter.
- complexity: Difficulty level of the default challenge the user will get. The possible values are:
  - EASY: Simple challenge.
  - MEDIUM: Medium level challenge.
  - HARD: Difficult challenge.
  - FORCE_HARD: Difficult challenge with an additional question. The user is required to solve an additional challenge, regardless of the results of the main one.
  Note
  
  The feature of challenge options and show rules is at the Preview stage.
- pre_check_type: Type of the default main challenge the user will get.
- challenge_type: Type of the default additional challenge the user will get.
- allowed_sites: List of hosts as IP addresses or domain names without http/https or / at the end, e.g., example.com. The CAPTCHA will also be valid for all subdomains of the specified domain names. This is an optional parameter.
- override_variant: Section containing the challenge option description. This is an optional parameter.
  - uuid: Unique ID of the challenge option.
  - description: Challenge option description. This is an optional parameter.
  - complexity: Difficulty level of the challenge the user will get.
  - pre_check_type: Type of the main challenge the user will get.
  - challenge_type: Type of the additional challenge the user will get.
- security_rule: Section describing the rule for incoming traffic that will determine which CAPTCHA option to show. This is an optional parameter.
  - name: Rule name.
  - priority: Rule priority, from 1 to 999999.
    
    Rules are checked in the ascending priority order, starting from 1, 2, etc. If traffic matches multiple rules, the first rule to trigger will apply.
  - description: Rule description. This is an optional parameter.
  - override_variant_uuid: ID of the challenge option to show if the traffic matches the rule. If the parameter is not specified, the user will get the default challenge.
  - condition: One or more conditions for the incoming traffic. This is an optional parameter.
For more information about the yandex_smartcaptcha_captcha resource parameters, see the provider documentation.
Create the resources:
1. In the terminal, change to the folder where you edited the configuration file.
2. Make sure the configuration file is correct using the command:
```
terraform validate
```
  If the configuration is correct, the following message is returned:
```
Success! The configuration is valid.
```
3. Run the command:
```
terraform plan
```
  The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
4. Apply the configuration changes:
```
terraform apply
```
5. Confirm the changes: type yes in the terminal and press Enter.
Terraform will create all the required resources. You can check the new resources using the management console or this CLI command:
```
yc smartcaptcha captcha list
```

To create a CAPTCHA, use the create REST API method for the Captcha resource or the Captcha/Create gRPC API call.

Creating a CAPTCHA

Was the article helpful?