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 whitelisted for the reCAPTCHA Enterprise API.

    reCAPTCHA Enterprise is not available for everyone at this time, so you must go through a whitelisting 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 whitelisted their account.

    Wait for a reply confirming that whitelisting is completed.

  1. Sign in to your Google Account.

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

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

    Go to the project selector page

  3. Make sure that billing is enabled for your Google Cloud project. Learn how to confirm 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.

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