reCAPTCHA is a part of Google Cloud Fraud Defense. For more information, see Google Cloud Fraud Defense.

Install Universal keys on web pages

This document describes how you can install and integrate a Universal key with your web pages.

Before you begin

Install Universal keys on your website

To install your Universal key and help protect your web pages, choose either the Google Cloud Fraud Defense AutoExecute configuration or the standard JavaScript installation:

AutoExecute configuration

Fraud Defense AutoExecute can help simplify your frontend JavaScript integration through intercepting network requests on your web pages, eliminating the need to manually call grecaptcha.enterprise.execute() for each frontend action.

AutoExecute only intercepts asynchronous network requests initiated with the Fetch API or XMLHttpRequest, including requests from frameworks like AJAX that use these APIs.
AutoExecute is not supported for resources that load automatically at page load time. Instead, apply AutoExecute to network requests triggered by user actions on the page, such as a login button.
To prevent Fraud Defense challenges from causing network timeouts, apply timeouts directly to the requests. Use AbortSignal.timeout(n) for the Fetch API and the XMLHttpRequest.timeout property for XMLHttpRequest.

Add the script tag to your web pages

To load reCAPTCHA on your web page, add the JavaScript API with your Universal key within the <head></head> element of your web page:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Fraud Defense uses the browser's language by default. If you want to specify a different language, use the hl=LANG attribute in your script. For example, to use French, specify the following:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

To learn about the supported languages, see language codes for Fraud Defense.

Configure protected endpoints

The Fraud Defense script automatically integrates with network actions defined in the policy configuration of your Universal key. This section defines a mapping of URL paths (path) to action names (action).

If the Fraud Defense script detects an asynchronous network request to a mapped path, it intercepts the request, triggers a risk evaluation, and potentially displays a CAPTCHA challenge to the user before the original request continues. The generated response token is automatically attached to the X-Recaptcha-Token header in the request.

gcloud

To inspect the current policy configuration for your Universal key, use the gcloud alpha recaptcha policies describe command:

gcloud alpha recaptcha policies describe --key=KEY_ID

To update the policy configuration with your protected endpoints, create a YAML file (for example, POLICY.yaml) defining your protected paths and actions:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Update your key configuration with the YAML file using the gcloud alpha recaptcha policies update command:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

REST API

To update the policy configuration to define protected endpoints using the REST API, use the projects.keys.updatePolicy method.

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

PROJECT_ID: your Google Cloud project ID
KEY_ID: the ID of your Universal key

HTTP method and URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

Request JSON body:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

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.

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

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.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

If successful, the request returns the updated policy configuration.

The path parameter supports glob patterns with the following rules:

Must start with / and cannot be empty.
Cannot be a standalone /* or /**, as it can negatively impact performance to trigger Fraud Defense on every single request to your backend.
Wildcards * (matching a single path segment) and ** (matching multiple path segments) must occupy the entirety of a path segment (for example, /api/*/login or /api/* are valid; /api/login* is invalid).
The ** wildcard must only occupy the last path segment (for example, /api/** is valid; /api/**/login is invalid).

Third-party requests: If third-party tools running on your page (such as analytics or partner scripts) send requests to paths that match your protected endpoints (for example, https://analytics.example.net/login matching /login), AutoExecute will also intercept them. This can cause extra network latency, skewed metrics, or unexpected CAPTCHA challenges. To avoid conflicts, ensure your protected paths are distinctive (for example, /auth/v1/login), or use the Standard installation if path collisions occur.
Cross-domain APIs: If your backend API is hosted on a different domain than your website (for example, examplecdn.net versus www.example.com), AutoExecute works automatically without extra domain configuration.

If matching against specific destination domains is important for your integration, file a feature request.

In your backend, get the response token from the X-Recaptcha-Token request header and create an assessment within two minutes.

Standard installation

We recommend that you add Fraud Defense verification on a user interaction that needs to be verified. For example, if you want to verify the submit action of a form, then you need to add Fraud Defense verification on the submit action.

Depending on where you want to add Fraud Defense verification, choose the appropriate option:

Add verification on a user interaction
Add Fraud Defense on an HTML button

Add verification on a user interaction

To load reCAPTCHA on your web page, add the JavaScript API with your Universal key within the <head></head> element of your web page:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense uses the browser's language by default. If you want to specify a different language, use the hl=LANG attribute in your script. For example, to use French, specify the following:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

To learn about the supported languages, see language codes for Fraud Defense.

If you want to specify a location for the badge, use badge=LOCATION as a query parameter in the script tag. For example, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. By default, the location is set to bottomright. Other possible values are inline and bottomleft.

To add Fraud Defense verification on a user interaction, do the following:

To help ensure that grecaptcha.enterprise.execute() runs after the Fraud Defense library loads, use grecaptcha.enterprise.ready().

Call grecaptcha.enterprise.execute() on each interaction that you want to protect with your Universal key. Specify a meaningful name for a user interaction in the action parameter. For more guidance, see Actions.

The following example shows how to call grecaptcha.enterprise.execute() on a login action:

<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>

After the token is generated, send the reCAPTCHA token to your backend and create an assessment within two minutes.

Important: Your backend must specify assessment.event.expected_action (or expectedAction in JSON) in the CreateAssessmentRequest, and it must match the action configured in the execute() call. For example, if you configure the frontend action to be LOGIN, your backend must set expected_action to LOGIN when creating an assessment for that request. If there is a mismatch, it indicates that an attacker is attempting to falsify actions.

Add Fraud Defense on an HTML button

To load reCAPTCHA on your web page, add the JavaScript API with your Universal key within the <head></head> element of your web page:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense uses the browser's language by default. If you want to specify a different language, use the hl=LANG attribute in your script. For example, to use French, specify the following:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

To learn about the supported languages, see language codes for Fraud Defense.
To add Fraud Defense on an HTML button, do the following:
1. Define a callback function to handle the token.
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
For more information, see the requestSubmit() method.
1. Add attributes to your HTML button.
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
If you want to specify a location for the badge, use the data-badge="LOCATION" attribute on the element that has class="g-recaptcha". By default, the location is set to bottomright. Other possible values are inline and bottomleft.
1. When this button is used to submit a form on your site, the g-recaptcha-response POST parameter contains the response token.
Note: If you set the g-recaptcha button as disabled, the button is enabled when Fraud Defense is loaded.
After the token is generated, send the reCAPTCHA token to your backend and create an assessment within two minutes.

Important: Your backend must specify assessment.event.expected_action (or expectedAction in JSON) in the CreateAssessmentRequest, and it must match the action configured on the button. For example, if you configure the button action to be submit, your backend must set expected_action to submit when creating an assessment for that request. If there is a mismatch, it indicates that an attacker is attempting to falsify actions.

What's next

To trigger CAPTCHA challenges based on custom rules, configure challenge policies.
To assess the reCAPTCHA response token, create an assessment.