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

  1. Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.

  2. Choose the appropriate key type. Learn more about reCAPTCHA keys.

  3. reCAPTCHA site keys for mobile applications (mobile keys) are accessible after a security review. Contact our sales team to onboard your site to this feature.

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 Cloud console. Alternatively, you can use the reCAPTCHA Enterprise API or the Google Cloud CLI.

Console

  1. In the console, go to the reCAPTCHA Enterprise page.

    Go to reCAPTCHA Enterprise

  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. Create a site key for a website or mobile platform. For instructions, expand the section that corresponds with your platform.
  6. Create site keys for websites

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

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

      The Domain list section appears.

    2. 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).

    3. 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:
        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.

            When you disable domain verification for challenge page site keys, Google Cloud Armor verifies the domain.

          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.
        2. Click Create key.

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

      • To create a checkbox site key to show a visible challenge to your users, do the following:
        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.

          When you disable domain verification for challenge page site keys, Google Cloud Armor verifies the domain.

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

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

      The Domain list section appears.

    2. 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).

    3. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
    4. Turn on the Web application firewall (WAF) toggle.
    5. From the Feature drop-down menu, select the type of WAF key you want to create.

    6. 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.

      When you disable domain verification for challenge page site keys, Google Cloud Armor verifies the domain.

    7. Optional: For action token site keys, turn on Use checkbox challenge.

    8. Click Create key.
    9. The newly created key is listed on the reCAPTCHA keys page.

    Create site keys for mobile applications

    You can create only score-based site keys for mobile applications.

    1. From the Choose platform type drop-down menu, select Android app or iOS app.
    2. Depending on the platform you selected, enter Android packages or iOS bundle IDs.

      If you selected Android app, do the following:

      1. In the Android package list section, click Add Android package.
      2. In the Android package field, enter the name of your Android package.

      3. Optional: To add an additional package, click Add Android package and enter the name of another Android package in the Android package field.

      If you selected iOS app, do the following:

      1. In the iOS bundle ID list section, click Add iOS bundle ID.
      2. In the Bundle ID field, enter the name of your iOS bundle ID.

      3. 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.

      For mobile applications, the reCAPTCHA site key is unique to the specified package names (for example, com.google.recaptcha.test).

    3. Click Create key.

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

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.
    • WAF_SERVICE (only for WAF site keys): name of the WAF service provider. Specify CA for Google Cloud Armor.
    • 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.
    • 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.

      When you disable domain verification for challenge page site keys, Google Cloud Armor verifies the domain.

  • 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 & CMD LINE

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: name of the WAF service provider. Specify CA for Google Cloud Armor.
  • WAF_FEATURE: name of the WAF feature.

    Depending on the type of keys, specify challenge-page, action-token, or session-token.

  • 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: 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.

    When you disable domain verification for challenge page site keys, Google Cloud Armor verifies the domain.

  • 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.
  • 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

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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 called request.json, and execute the following command:

$cred = gcloud auth application-default 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"
  }
}





What's next