Migrating from reCAPTCHA

This page explains how to migrate from reCAPTCHA to reCAPTCHA Enterprise. This assumes you already have a site that is instrumented to generate tokens using reCAPTCHA v2 or v3.

Before you begin

1. Get on the allowlist for the reCAPTCHA Enterprise API.

   reCAPTCHA Enterprise is not available for everyone at this time, so you must go through a allowlisting process to gain access.

   Complete the reCAPTCHA Enterprise Program form. You will need to include the following information:

   • Email address for someone who is an owner of the Google Cloud project. This person will be able to enable the reCAPTCHA Enterprise API once we have allowed their account.

   Wait for a reply confirming that enabling the account is completed.

2. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

3. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to the project selector page

4. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

5. Enable the reCAPTCHA Enterprise API.

   Enable the API

Keys

You must create new keys. These keys will replace any Site Keys you created in reCAPTCHA. The table below describes the mappings from reCAPTCHA keys to reCAPTCHA Enterprise keys:

reCAPTCHA	reCAPTCHA Enterprise
reCAPTCHA v2 Checkbox	CHECKBOX
reCAPTCHA v2 Invisible	INVISIBLE
reCAPTCHA v3	SCORE

Web page instrumentation

You should already have this script included in some of your pages: https://www.google.com/recaptcha/api.js.

• Change the api.js component to enterprise.js.
• Replace calls to grecaptcha.execute with grecaptcha.enterprise.execute.
• Update the site key parameter to point to the new key.

API Request

You must replace the backend call to https://www.google.com/recaptcha/api/siteverify with one to https://recaptchaenterprise.googleapis.com. The fastest way to migrate the backend call is to use the v1beta API, outlined below.

Note: Although utilizing the v1beta1 endpoint is the fastest way to migrate from reCAPTCHA to reCAPTCHA Enterprise due to the similar use of API keys, we recommend moving to the v1 endpoint when possible. Note that some features, such as logging within Google Cloud Operations , are only available for the v1 API.

Before using any of the request data below, make the following replacements:

• API_KEY: API key associated with the current project
• project-id: your GCP project ID
• token: token returned from the `grecaptcha.enterprise.execute()` call
• key: reCAPTCHA Key associated with the site/app

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1beta1/projects/project-id/assessments?key=API_KEY

Request JSON body:

{
  "event": {
    "token": "token",
    "siteKey": "key"
  }
}

To send your request, choose one of these options:

curl

Note: Create an API key to authenticate with the API.

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

curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://recaptchaenterprise.googleapis.com/v1beta1/projects/project-id/assessments?key=API_KEY

PowerShell

Note: Create an API key to authenticate with the API.

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

$headers = @{  }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://recaptchaenterprise.googleapis.com/v1beta1/projects/project-id/assessments?key=API_KEY" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "score": 0.1,
  "reasons": ["AUTOMATION"],
  "event": {
    "token": "token",
    "siteKey": "key"
   },
  "name": "projects/project-id/assessments/b6ac310000000000"
}

What's next

• Learn how to interpret an assessment.
• Learn how to use the v1 Assessment API.