Create reCAPTCHA keys for websites

This page explains how to create reCAPTCHA keys (also known as keys) to verify user interactions on your web pages.

reCAPTCHA keys represent how reCAPTCHA is configured for a website. The configuration includes important options such as whether to show CAPTCHA challenges.

Before you begin

• Prepare your environment for reCAPTCHA.
• Ensure that you have the following Identity and Access Management role: reCAPTCHA Enterprise Admin (roles/recaptchaenterprise.admin).
• Choose the key type that is best for your use case.

Create a reCAPTCHA key

There is no limit on the number of reCAPTCHA keys that you can create for a Google Cloud project. It is best to create one reCAPTCHA key per website.

We recommend creating separate reCAPTCHA keys for staging and production environments. Otherwise, you risk polluting reCAPTCHA risk analysis with data from your test environment.

The simplest way to create a reCAPTCHA key is through the reCAPTCHA admin console. Alternatively, you can use the Google Cloud console, reCAPTCHA Enterprise API, or the Google Cloud CLI.

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 .

   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

Note: Creating a score-based key is the default option in the Google Cloud console.

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

We do not recommend using checkbox keys because they increase user friction and don't significantly improve accuracy.

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.
  Note: We do not recommend using CHECKBOX because it increases user friction and doesn't significantly improve accuracy. For more information, see the FAQs.
• 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.

  Note: 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).

Execute the gcloud recaptcha keys create command:

Linux, macOS, or Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

For API reference information about key types and integration types, see Key and Integration type.

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.
  Note: We do not recommend using CHECKBOX because it increases user friction and doesn't significantly improve accuracy. For more information, see the FAQs.
• 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.

  Note: 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).

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

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"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$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"
  }
}

Note: After creating reCAPTCHA keys, you can edit or delete them. You cannot recover deleted keys. Also, you cannot migrate reCAPTCHA keys from one Google Cloud project to another Google Cloud project.

(Optional) Find a legacy reCAPTCHA secret key

If you want to integrate with a third-party application that does not use the reCAPTCHA Enterprise API, you need the legacy secret key.

For every site key that you create, reCAPTCHA creates a legacy reCAPTCHA secret key (legacy secret key), which you can use with your third-party application.

Note: We don't recommend using a legacy secret key on your frontend because it will be visible to your users and attackers can abuse your application.

To find the legacy secret key, do the following:

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

   Go to reCAPTCHA

2. In the reCAPTCHA Keys section, find the reCAPTCHA key that you created and click the key.

   

3. On the Key Details page, under the Integration tab, click Use Legacy Key. A dialog opens with instructions on how to use the legacy secret key.

   

What's next

• Install score-based keys on your web pages.
• Install checkbox keys on your web pages.