Creating reCAPTCHA keys

This page explains how to create reCAPTCHA keys, also known as site keys, to verify user interactions on your web pages and mobile applications.

reCAPTCHA site keys represent how reCAPTCHA Enterprise is configured for a site or an app. The configuration includes important options such as whether to show CAPTCHA challenges. reCAPTCHA site keys are different from API keys.

Before you begin

Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.
Choose the appropriate key type. Learn more about reCAPTCHA keys.

Creating a site key

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

Create separate site 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 site key is through the Google Cloud console. Alternatively, you can use the reCAPTCHA Enterprise API or the Google Cloud CLI.

Console

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

Go to reCAPTCHA Enterprise
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.
Click Create key.
In the Display name field, enter a display name for the key.
Create a site key for a website or mobile platform. For instructions, expand the section that corresponds with your platform.

Create site keys for websites

You can create score-based and checkbox keys for websites.

From the Choose platform type drop-down menu, select Website.

The Domain list section appears.
Enter the domain name for your website:

If you want to create a challenge page site key, skip this step.
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 site 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).
Depending on the type of site key you want to create, perform the appropriate actions:
- To create a score-based site key (recommended), do the following:
  Note: Creating a score-based site 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 site 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 site 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.
  2. To create a checkbox site key to show a visible challenge to your users, do the following:
    We do not recommend using checkbox site 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 site 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.

Create site keys for Web Application Firewall (WAF)

You can create WAF site keys for websites. To create a Web application firewall (WAF) key, do the following:

From the Choose platform type drop-down menu, select Website.

The Domain list section appears.
Enter the domain name for your website:

If you want to create a challenge page site key, skip this step.
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 site 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).
Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
Turn on the Web application firewall (WAF) toggle.
From the Feature drop-down menu, select the type of WAF key you want to create.
For challenge page site keys, turn on Disable domain verification. For action token and session token site keys, this step is optional.

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.
Optional: For action token site keys, turn on Use checkbox challenge.
Click Create key.

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

Create keys for iOS applications

You can create only score-based keys for iOS applications.

We recommend creating one reCAPTCHA key per iOS application.

From the Choose platform type drop-down menu, select iOS app.

In the iOS bundle ID list section, click Add iOS bundle ID.
In the Bundle ID field, enter the name of your iOS bundle ID.
Optional: To add an additional bundle ID, click Add iOS bundle ID and enter the name of your iOS bundle ID in the Bundle ID field.
Optional: Provide Apple Developer settings.

We recommend providing this data because it allows reCAPTCHA Enterprise to provide more accurate risk scores for your traffic.

Enter the following information:
- Private key (.p8): This is generated in the Apple Developer Center under Certificates, Identifiers & Profiles.
- Key identifier: The Apple developer key identifier (10-character string).
- Team ID: The Apple team ID (10-character string) owning the provisioning profile that is used to build your application.
Optional: To verify bundle IDs, do the following:
1. Expand Bundle ID verification.
2. To protect the reCAPTCHA key for your bundle IDs, ensure that the Disable bundle ID verification toggle is turned off.
3. For your non-production environment, if you want to specify a score that 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.

Create keys for Android applications

You can create only score-based keys for Android applications.

We recommend the following when creating keys for mobile applications:

Create one reCAPTCHA key for each mobile application.
For Android keys, create separate keys for the following scenarios:
- Package is only available on Google Play Store.
- Package is only available on non-Google Play Store app stores.
- Package is available in both the Google Play Store and non-Google Play Store app stores.

In the Android package list section, click Add Android package.
In the Android package field, enter the name of your Android package.
Optional: To add an additional package, click Add Android package and enter the name of another Android package in the Android package field.
Optional: Expand Package name verification, app distribution, and testing keys.

To enforce that reCAPTCHA key is only used within your app, turn off the Disable package name verification toggle.
If you want to create a key for an application that is available on other app stores in addition to the Google Play Store, turn on Support applications distributed outside of the Google Play Store.
For your non-production environment, if you want to specify a score that 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.

gcloud

To create keys, use the gcloud recaptcha keys create command:

To create keys for websites, use the following command:
```
  gcloud recaptcha keys create \
    --web \
    --display-name=DISPLAY_NAME  \
    --waf-feature=WAF_FEATURE \
    --waf-service=WAF_SERVICE \
    --integration-type=INTEGRATION_TYPE \
    --domains=DOMAIN_NAME
```
Provide the following values:
- DISPLAY_NAME: name for the key. Typically a site name.
- WAF_FEATURE (only for WAF site keys): name of the WAF feature. Possible values are the following: challenge-page, action-token, and session-token.
  Note: You can use a WAF site key only for the corresponding feature. For example, you can use the action-token site key only for reCAPTCHA action-token. You cannot use this key for other websites and mobile platforms.
- WAF_SERVICE (only for WAF site keys): name of the WAF service provider. Specify CA for Google Cloud Armor or fastly for Fastly.
- INTEGRATION_TYPE: Type of integration. Depending on the type of keys, specify the following values:
  - score for score-based site keys.
  - checkbox for checkbox site keys.
  - invisible for challenge-page site keys.
  - score or checkbox for action-token site keys.
  - score for session-token site 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. Optional: For WAF site keys, specify --allow-all-domains to disable domain verification.
  
  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 site 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 create keys for Android apps, use the following command:
```
    gcloud recaptcha keys create \
      --android --package-names=PACKAGE_NAMES \
      --display-name=DISPLAY_NAME
    
```
Provide the following values:
- DISPLAY_NAME: name for the key. Typically an app name.
- PACKAGE_NAMES: Android package names of apps allowed to use the key. Specify multiple package names as a comma-separated list.
To create a key for iOS apps, use the following command:
```
    gcloud recaptcha keys create \
      --ios --bundle-ids=BUNDLE_IDs \
      --display-name=DISPLAY_NAME
    
```
Provide the following values:
- DISPLAY_NAME: name for the key. Typically an app name.
- BUNDLE_IDs: iOS bundle ids of apps allowed to use the key. Specify multiple bundle IDs as a comma-separated list.

The following example shows a sample output of creating a key using the gcloud recaptcha keys create command.

  Created [6Ld3howaAAAAAFYDMsLz2nWFXhsnmBjdrBra5_Bq].

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:

PROJECT_ID: your Google Cloud project ID
DISPLAY_NAME: display name for the key
WAF_SERVICE (only for WAF site keys): name of the WAF service provider. Specify CA for Google Cloud Armor or fastly for Fastly.
WAF_FEATURE: name of the WAF feature.
Depending on the type of keys, specify challenge-page, action-token, session-token, or express.

Note: You can use a reCAPTCHA WAF site key only for its corresponding feature. You cannot use this key for other websites and mobile platforms.
DOMAINS (for websites and WAF only): domains or subdomains of websites allowed to use the key.
Specify multiple domains as a comma-separated list. Optional: For WAF site keys, specify --allow-all-domains to disable domain verification.

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 site 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).
TYPE_OF_INTEGRATION (for websites and WAF only): Depending on the type of keys, specify the following values:
- SCORE for score-based site keys.
- CHECKBOX for checkbox site keys.
- INVISIBLE for challenge-page site keys.
- SCORE or CHECKBOX for action-token site keys.
- SCORE for session-token site 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.
PACKAGE_NAMES (for Android apps only): Android package names of apps allowed to use the key. Specify multiple package names as a comma-separated list.
BUNDLE_IDs (for iOS apps only): iOS bundle ids of apps allowed to use the key. Specify multiple bundle IDs as a comma-separated list.

HTTP method and URL:

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

Request JSON body:



To create keys for websites:
{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
  }
}


To create keys for WAF:

{
   "displayName": "DISPLAY_NAME",
    'wafSettings': "  {
        "wafService": "WAF_SERVICE",
"wafFeature": "WAF_FEATURE"
   }
   "webSettings": {
     "allowedDomains": "DOMAINS",
     "integrationType": "TYPE_OF_INTEGRATION"
    }
}

To create keys for Android apps:
{
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
  "allowedPackageNames":"PACKAGE_NAMES"
  }
}

To create keys for iOS apps:

{
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
   "allowedBundleIds":"BUNDLE_IDs"

  }
}

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

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

(Optional) Find a legacy reCAPTCHA secret key

If you want to integrate with a third-party application that uses the non-Enterprise version of reCAPTCHA, you need the legacy secret key.

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

To find the legacy secret key, do the following:

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

Go to reCAPTCHA Enterprise
In the Enterprise Keys section, find the site key that you created and click the key.
On the Key Details page, expand Legacy reCAPTCHA secret key.

What's next

Install score-based site keys or checkbox site keys on web pages.
Integrate mobile keys within iOS apps or Android apps.
Implement the reCAPTCHA Enterprise for WAF and Google Cloud Armor integration.