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
Go to the reCAPTCHA admin console.
- In the Label field, enter a name that you can use to identify your site.
- If you want to create a score-based key, select Score based (v3). If you want to create a checkbox key, select Challenge (v2).
- 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.
.
- If you are new to the Google Cloud console, then read the terms of service, and select the checkbox.
- 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
In the Google Cloud console, go to the reCAPTCHA page.
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.
- From the Choose platform type menu, select
Website.
The Domain list section appears.
-
Enter the domain name for your website:
- In the Domain list section, click Add a domain.
- In the Domain field, enter the name of your domain.
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.
- Depending on the type of reCAPTCHA key you want to create for your website, perform the appropriate action:
- 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.
-
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.
- 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.
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:
- Click the This is a testing key toggle.
- In the Score box, specify a score between 0 to 1.0.
- Click Create key.
The newly created key is listed on the reCAPTCHA keys page.
-
To protect the reCAPTCHA key for your domain and subdomains,
ensure that the Disable domain verification
toggle is turned off.
- Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge
section.
-
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.
- Turn on the Use checkbox challenge toggle.
- 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.
-
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:
- Click the This is a testing key toggle.
- In the Score box, specify a score between 0 to 1.0.
- 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.
- Click Create key.
The newly created key is listed on the reCAPTCHA keys page.
Create score-based reCAPTCHA keys
Create checkbox reCAPTCHA keys
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 thetokenProperties.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:
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.
- 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 thetokenProperties.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
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 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.
To find the legacy secret key, do the following:
In the Google Cloud console, go to the reCAPTCHA page.
In the reCAPTCHA Keys section, find the reCAPTCHA key that you created and click the key.
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.