Create reCAPTCHA keys for websites

Admin console

1. Go to the reCAPTCHA admin console.

   Go to reCAPTCHA admin console

2. In the Label field, enter a name that you can use to identify your site.
3. If you want to create a score-based key, select Score based (v3). If you want to create a checkbox key, select Challenge (v2).
4. To add a domain, enter your domain name and click add .

   To add an additional domain, you can repeat this step. You can add up to a maximum of 250 domains.

5. If you are new to the Google Cloud console, then read the terms of service, and select the checkbox.
6. Click Submit.

If you are new to the Google Cloud console, then a Google Cloud project is created and the necessary APIs are enabled for you to get started. If you already have a Google Cloud project, then the necessary APIs are enabled for your project to get started.

Cloud console

1. In the Google Cloud console, go to the reCAPTCHA page.

   Go to reCAPTCHA

2. Verify that the name of your project appears in the resource selector at the top of the page.

   If you don't see the name of your project, click the resource selector, then select your project.

3. Click Create key.
4. In the Display name field, enter a display name for the key.
5. From the Choose platform type menu, select Website.

   The Domain list section appears.

6. Enter the domain name for your website:

   1. In the Domain list section, click Add a domain.
   2. In the Domain field, enter the name of your domain.

   3. Optional: To add an additional domain, click Add a domain and enter the name of another domain in the Domain field. You can add up to a maximum of 250 domains.

      For websites, the reCAPTCHA key is unique to the domains and subdomains that you specify. You can specify more than one domain if you serve your website from multiple domains. If you specify a domain (for example, examplepetstore.com), you do not need to specify its subdomains (for example, subdomain.examplepetstore.com).

      To use a key on more than 250 domains, click the Disable domain verification toggle. reCAPTCHA will then ignore the domain list. You need to perform domain verification yourself by examining the tokenProperties.hostname field in the assessments you create.

7. Depending on the type of reCAPTCHA key you want to create for your website, perform the appropriate action:

Create score-based reCAPTCHA keys

1. Optional: If you want to disable domain verification or allow AMP pages, expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
   
   1. To protect the reCAPTCHA key for your domain and subdomains, ensure that the Disable domain verification toggle is turned off.

      Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

      
   2. If you want to allow the score-based key to work with Accelerated Mobile Pages, (AMP), turn on the Allow this key to work with AMP pages toggle.

   3. For your non-production environment, if you want to specify a score you want the key to return when any assessments are created for it, do the following:

      1. Click the This is a testing key toggle.
      2. In the Score box, specify a score between 0 to 1.0.
      
   4. Click Create key.

   The newly created key is listed on the reCAPTCHA keys page.

Create checkbox reCAPTCHA keys

1. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
   
2. To protect the reCAPTCHA key for your domain and subdomains, ensure that the Disable domain verification toggle is turned off.

   Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

   
3. Turn on the Use checkbox challenge toggle.
   
4. Select the appropriate Challenge security option.

   The challenge security option controls the probability of a user being prompted for a secondary challenge in which users are prompted to select images based on an identified category (example, select the pictures with a motorcycle, or stairs).

   

   If you want to ensure the best anti-fraud protection, select Harder difficulty (more secure against bots).

   If you select Easiest challenge difficulty, the users are less likely to be prompted with the visual challenge.

5. For your non-production environment, if you want to specify a score you want the key to return when any assessments are created for it, do the following:

   1. Click the This is a testing key toggle.
   2. In the Score box, specify a score between 0 to 1.0.
   3. Select the appropriate Challenge type option.
      • Auto pops up the challenge sometimes.
      • No CAPTCHA does not show a challenge.
      • Unsolvable challenge shows the images but the challenge is not passed.
      
   4. Click Create key.

   The newly created key is listed on the reCAPTCHA keys page.

gcloud

To create reCAPTCHA keys, use the gcloud recaptcha keys create command.

Before using any of the command data below, make the following replacements:

• DISPLAY_NAME: Name for the key. Typically a site name.
• INTEGRATION_TYPE: Type of integration. Depending on the type of keys, specify the following values:
  • score for score-based keys.
  • checkbox for checkbox keys.
• DOMAIN_NAME: Domains or subdomains of websites allowed to use the key.

  Specify multiple domains as a comma-separated list.

  To use a key on more than 250 domains, specify --allow-all-domains to disable domain verification. reCAPTCHA will then ignore the domain list. You need to perform domain verification yourself by examining the tokenProperties.hostname field in the assessments you create.

  Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

Execute the gcloud recaptcha keys create command:

gcloud recaptcha keys create \
        --web \
        --display-name=DISPLAY_NAME  \
        --integration-type=INTEGRATION_TYPE \
        --domains=DOMAIN_NAME

gcloud recaptcha keys create `
        --web `
        --display-name=DISPLAY_NAME  `
        --integration-type=INTEGRATION_TYPE `
        --domains=DOMAIN_NAME

gcloud recaptcha keys create ^
        --web ^
        --display-name=DISPLAY_NAME  ^
        --integration-type=INTEGRATION_TYPE ^
        --domains=DOMAIN_NAME

The response contains the newly created reCAPTCHA key.

REST

Before using any of the request data, make the following replacements:

• DISPLAY_NAME: Name for the key. Typically a site name.
• INTEGRATION_TYPE: Type of integration. Depending on the type of keys, specify the following values:
  • score for score-based keys.
  • checkbox for checkbox keys.
• DOMAIN_NAME: Domains or subdomains of websites allowed to use the key.

  Specify multiple domains as a comma-separated list.

  To use a key on more than 250 domains, specify --allow-all-domains to disable domain verification. reCAPTCHA will then ignore the domain list. You need to perform domain verification yourself by examining the tokenProperties.hostname field in the assessments you create.

  Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

Request JSON body:

{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
  }
}

To send your request, choose one of these options:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      DOMAINS
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}