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. Sign in to your Google Account.

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

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

    Go to the project selector page

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

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

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

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

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