Use reCAPTCHA features after migration

This page explains how to modify an existing reCAPTCHA integration to use reCAPTCHA features, such as Multi-factor authentication (MFA) and Password Leak Detection after migrating from reCAPTCHA Classic. Modifying an existing reCAPTCHA integration involves instrumenting the web pages and migrating the backend calls.

Before you begin

Migrate to reCAPTCHA.

Instrument the web pages

To instrument the web pages with the reCAPTCHA scripts and calls, do the following:

  1. Verify that you have the following script included in your web pages: https://www.google.com/recaptcha/api.js.

  2. In your web pages, replace https://www.google.com/recaptcha/api.js with https://www.google.com/recaptcha/enterprise.js.

  3. If you programmatically invoke the API, then replace the following calls:

    • grecaptcha.execute() -> grecaptcha.enterprise.execute()
    • grecaptcha.getResponse() -> grecaptcha.enterprise.getResponse()
    • grecaptcha.ready() -> grecaptcha.enterprise.ready()
    • grecaptcha.render() -> grecaptcha.enterprise.render()
    • grecaptcha.reset() -> grecaptcha.enterprise.reset()

(Optional) To improve the loading performance of reCAPTCHA, do the following:

  1. Verify that you are loading enterprise.js asynchronously. For more information, see Loading reCAPTCHA asynchronously.

  2. Add the following resource hints in the <head> tag of pages that load enterprise.js:

    • <link rel="preconnect" href="https://www.google.com">
    • <link rel="preconnect" href="https://www.gstatic.com" crossorigin>

Migrate the backend calls

To use reCAPTCHA features, you must migrate your backend calls to the new endpoints and set up authentication:

  1. Replace backend calls to https://www.google.com/recaptcha/api/siteverify with equivalent calls to recaptchaenterprise.googleapis.com. For the complete URL and the POST data format, see Create an assessment for your website.

  2. Set up authentication to reCAPTCHA.

    The authentication method you choose depends on the environment where reCAPTCHA is set up. The following table helps you choose the appropriate authentication method and the supported interface to set up authentication:

    Environment Interface Authentication method
    Google Cloud
    • REST
    • Client libraries
    		 Use attached service accounts.
    On-premises or a different cloud provider REST Use API keys or Workload Identity Federation.

    If you want to use API keys, then we recommend securing the API keys by applying API key restrictions.
    Client libraries

    Use the following:

What's next