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.

  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


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

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:


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 \


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