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.

  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 gcloud command-line tool.

Console

  1. In the Cloud 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.

    Create site keys for websites

    You can create checkbox and score-based site 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:

      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. To protect the reCAPTCHA site key for your domain and subdomains, ensure that Verify domains is selected.

      If you do not select this option, it is a security risk because your reCAPTCHA key can be accessed and used by anyone, as there are no restrictions on the site.

    4. From the Integration type drop-down menu, select the appropriate key type.

    5. Depending on the integration type that you selected, perform the appropriate action:
      • If you selected the Scoring, with no visible challenge to your users (recommended) option, you can optionally allow this key to work with Accelerated Mobile Pages (AMP).
      • If you selected the Checkbox ("I'm not a robot") with scoring option, 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.

    6. Click Create key.

    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.

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 below, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • DISPLAY_NAME: display name for the key
  • DOMAINS (for websites only): domains or subdomains of websites allowed to use the key. Specify multiple domains as a comma-separated list.
  • TYPE_OF_INTEGRATION (for websites only): SCORE or CHECKBOX.
  • 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 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"
  }
}

gcloud

Use the gcloud alpha recaptcha keys create command as shown in the following examples:

  • To create keys for websites, use the following command:

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

    Provide the following values:

    • DISPLAY_NAME: name for the key. Typically a site name.
    • INTEGRATION_TYPE: Type of integration, SCORE or CHECKBOX.
    • DOMAINS: Domains or subdomains of websites allowed to use the key. Specify multiple domains as a comma-separated list.

  • To create keys for Android apps, use the following command:

    gcloud alpha 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 alpha 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 alpha recaptcha keys create command.

  Created [6Ld3howaAAAAAFYDMsLz2nWFXhsnmBjdrBra5_Bq].

What's next