Migrate from reCAPTCHA Classic

This document shows you how to migrate from reCAPTCHA Classic to reCAPTCHA by using an active site key. The migration process takes 5–10 minutes to complete and requires no code changes.

If you access the reCAPTCHA Admin console, then you are using reCAPTCHA Classic, which has limited capabilities and strict limits on monthly usage. For more information about the features comparison, see Comparison of features between reCAPTCHA versions.

After the migration, you become a user of reCAPTCHA and you are charged when you exceed 10,000 requests per month. For more information, see reCAPTCHA pricing.

Note: reCAPTCHA v2 Android keys cannot be migrated.

Note: The migration process does not provide access to the additional reCAPTCHA features such as Multi-factor authentication (MFA) or password leak detection. To use these additional features, see Using reCAPTCHA features after migration.

Note: The access controls on the destination Google Cloud project might prevent you from accessing the key in the reCAPTCHA Admin console after it is migrated. In this case, you need to use the Google Cloud console instead.

Before you begin

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

2. Make sure that billing is enabled for your Google Cloud project.

   reCAPTCHA requires billing to be linked and enabled on the project for the migration. You can enable billing by using either a credit card or an existing Google Cloud project billing ID. If you require assistance with billing, contact the Cloud Billing Support.

3. If you want to run the gcloud CLI outside of the Google Cloud console, install and initialize the gcloud CLI. For instructions, see

   Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

Enable the reCAPTCHA Enterprise API

Console

1. In the Google Cloud console, go to the reCAPTCHA Enterprise API page.

   Go to reCAPTCHA Enterprise API

2. Verify that the name of your project appears in the project selector at the top of the page.

   If you don't see the name of your project, click the project selector, and then select your project.

3. Click Enable.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. To set your Google Cloud project in the gcloud session, run the gcloud config set project command. Replace PROJECT_ID with your Google Cloud project ID.

          gcloud config set project PROJECT_ID
          

3. To enable the reCAPTCHA Enterprise API, run the gcloud services enable command:

            gcloud services enable recaptchaenterprise.googleapis.com
          

4. To verify that the reCAPTCHA Enterprise API is enabled, run the gcloud services list command:

            gcloud services list --enabled
          

   Verify that the reCAPTCHA Enterprise API is listed in the list of enabled APIs.

Migrate to reCAPTCHA

To migrate reCAPTCHA Classic to reCAPTCHA, choose an active site key from the reCAPTCHA Admin console, and migrate the site key. You can migrate one or more active site keys. However, you can migrate only one site key at a time.

To execute the migration process, you must have a reCAPTCHA user account that satisfies the following requirements:

• In the reCAPTCHA Admin console, the user account is listed as an owner for the site key you want to migrate.
• The user account has one of the following IAM roles for the Google Cloud project for which the reCAPTCHA Enterprise API is enabled:
  • Project Owner (roles/owner)
  • Project Editor (roles/editor)
  • reCAPTCHA Admin (roles/recaptchaenterprise.admin)
  If your user account doesn't have one of these roles, ask your administrator to grant the role, or follow the instructions in Granting, changing, and revoking access.

1. Migrate the site key by using Google Cloud console, Cloud Shell, the Google Cloud CLI, or the reCAPTCHA Enterprise API.

   Migrating the site key doesn't affect the key or the API endpoints; it adds the key to the enterprise license.

   Google Cloud console

   1. In the Google Cloud console, go to the reCAPTCHA page.

      Go to reCAPTCHA

   2. 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, and then select your project.

   3. From the Classic keys section, identify the key you want to migrate, and click Upgrade key.

      

   4. To complete the migration of the selected key, click Confirm.

   Cloud Shell

   1. In the Google Cloud console, go to Cloud Shell.

      Go to Cloud Shell

   2. If prompted, click Authorize.

   3. Choose and copy an active site key that you have used to integrate reCAPTCHA with your web pages:

      1. Go to the reCAPTCHA Admin console and click .

      2. Choose a site key. The following reCAPTCHA site keys are supported for migration: reCAPTCHA v2 Checkbox, reCAPTCHA v2 Invisible, and reCAPTCHA v3.

      3. To copy the site key, click Copy site key.

   4. Migrate the site key.

      Use the gcloud recaptcha keys migrate command as shown in the following example:

       gcloud recaptcha keys migrate SITE_KEY --project PROJECT-ID
      

      Provide the following values:

      • SITE_KEY: the active site key that you copied from the reCAPTCHA Admin console.
      • PROJECT-ID: the ID of the Google Cloud project for which the reCAPTCHA Enterprise API is enabled.

   gcloud CLI

   1. To configure authentication, run the following gcloud command:

      gcloud auth login
      

      Log in with the reCAPTCHA user account that owns the chosen site key and has one of the following roles: Project Owner, Project Editor, or reCAPTCHA Enterprise Admin role.

   2. Choose and copy an active site key that you have used to integrate reCAPTCHA with your web pages:

      1. Go to the reCAPTCHA Admin console and click .

      2. Choose a site key. The following reCAPTCHA site keys are supported for migration: reCAPTCHA v2 Checkbox, reCAPTCHA v2 Invisible, and reCAPTCHA v3.

      3. To copy the site key, click Copy site key.

   3. Migrate the site key.

      Use the gcloud recaptcha keys migrate command as shown in the following example:

       gcloud recaptcha keys migrate SITE_KEY --project PROJECT-ID
      

      Provide the following values:

      • SITE_KEY: the active site key that you copied from the reCAPTCHA Admin console.
      • PROJECT-ID: the ID of the Google Cloud project for which the reCAPTCHA Enterprise API is enabled.

   REST API

   1. Choose and copy an active site key that you have used to integrate reCAPTCHA with your web pages:

      1. Go to the reCAPTCHA Admin console and click .

      2. Choose a site key. The following reCAPTCHA site keys are supported for migration: reCAPTCHA v2 Checkbox, reCAPTCHA v2 Invisible, and reCAPTCHA v3.

      3. To copy the site key, click Copy site key.

   2. Migrate the site key.

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

      • PROJECT_ID: the ID of the Google Cloud project for which the reCAPTCHA API is enabled.
      • SITE_KEY: the active site key that you copied from the reCAPTCHA Admin console.

      HTTP method and URL:

      POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate

      To send your request, choose one of these options:

      curl

      Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

      Execute the following command:

      curl -X POST \
           -H "Authorization: Bearer $(gcloud auth print-access-token)" \
           -H "Content-Type: application/json; charset=utf-8" \
           -d "" \
           "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate"

      PowerShell

      Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

      Execute the following command:

      $cred = gcloud auth print-access-token
      $headers = @{ "Authorization" = "Bearer $cred" }
      
      Invoke-WebRequest `
          -Method POST `
          -Headers $headers `
          -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate" | Select-Object -Expand Content

      You should receive a JSON response similar to the following:

      {
        "name": "projects/PROJECT-ID/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
        "displayName": "My site key",
        "webSettings": {
          "allowAllDomains": false,
          "allowedDomains": [
            recaptcha.net
          ],
          "allowAmpTraffic": false,
          "integrationType": "SCORE",
          "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
        }
      }
      

2. To verify that the site key is migrated, do the following:

   Google Cloud console

   Go to the reCAPTCHA page and find the migrated site key in the reCAPTCHA keys section.

   Go to reCAPTCHA

   Cloud Shell

   Run the gcloud recaptcha keys list command and find the migrated site key in the list of keys.

   gcloud CLI

   Run the gcloud recaptcha keys list command and find the migrated site key in the list of keys.

After migrating to reCAPTCHA, you can continue to use the siteverify method to assess a user's reCAPTCHA response token.

Note: You shouldn't delete site keys from the reCAPTCHA Admin console or the reCAPTCHA page of Google Cloud console. When you delete a site key, it is deleted from both consoles and it removes the protection that reCAPTCHA offers.

You can revoke the reCAPTCHA Enterprise Admin (roles/recaptchaenterprise.admin) IAM role from your reCAPTCHA user account. You can either ask your administrator to revoke the access, or follow the instructions on Granting, changing, and revoking access.

What's next

• Use reCAPTCHA features after migration.