Create assessments for websites

This page explains how to create an assessment to allow your backend to verify the authenticity of the token that reCAPTCHA sends. reCAPTCHA sends an encrypted response, the reCAPTCHA response token (also known as token), when the end user triggers an HTML action.

For any type of reCAPTCHA key integration (checkbox, score, or Universal), you must create an assessment to assess the results of execute() in your backend by submitting the generated token to the assessment endpoint. reCAPTCHA processes the submitted token and reports the token's validity and score.

The first 10,000 reCAPTCHA monthly assessments are free. To continue creating assessments after you reach the free monthly usage limit (10,000 assessments per month), you must enable billing for your Google Cloud project. For more information about billing for reCAPTCHA, see Billing information.

Before you begin

1. Prepare your environment for Google Cloud Fraud Defense.
2. Ensure that you have the following Identity and Access Management role: reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent).
3. Install score-based keys, checkbox keys, or policy-based challenge keys on your website.
4. Set up authentication to Fraud Defense.

   The authentication method you choose depends on the environment where Fraud Defense 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: For Python or Java, 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. For other languages, use Workload Identity Federation.

Retrieve a token

Retrieve a token from web pages in one of the following ways:

• The resolved value of the promise returned by the call to grecaptcha.enterprise.execute().
• Use the g-recaptcha-response POST parameter when a user submits a form on your site.
• As a string argument to your callback function if data-callback is specified in either the g-recaptcha HTML tag attribute or the callback parameter in the grecaptcha.enterprise.render method.

You can access each user's token only once. If you need to assess a subsequent action that a user takes on your site, or if a token expires before an assessment is created, you must call execute() again to generate a new token.

Create an assessment

After you set up authentication, create an assessment by sending a request to the reCAPTCHA Enterprise API or by using the reCAPTCHA Client Libraries.

To improve detection, we recommend that you pass the following additional values when creating assessments:

• userAgent: The user agent is included in the HTTP request in the request header. For more information, see Learn about the User-Agent request header in the Mozilla Developer Network documentation.
• userIpAddress: The IP address of the user sending a request to your backend is available in the HTTP request. If you use a proxy server, the IP address is available in the X-Forwarded-For request header. For more information about getting the IP address, see X-Forwarded-For.
• ja4: JA4 is an open source method for fingerprinting TLS clients. For more information about how to create a JA4 fingerprint, see the JA4 documentation on GitHub.
• ja3: JA3 is an open source method for fingerprinting TLS clients. For more information about how to create a JA3 fingerprint, see the JA3 documentation on GitHub.

This helps in protecting your website and mobile applications against advanced attack patterns and human-led abuse.

The way you create an assessment is the same for score-based keys, checkbox keys, policy-based challenge, and Universal keys.

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja4": "JA4",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

curl -X POST \
     -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/assessments"

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
  },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja4": "JA4",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
  },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

  using System;
  using Google.Api.Gax.ResourceNames;
  using Google.Cloud.RecaptchaEnterprise.V1;

  public class CreateAssessmentSample
  {
      // Create an assessment to analyze the risk of a UI action.
      // projectID: Google Cloud project ID.
      // recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use reCAPTCHA Enterprise.
      // token: The token obtained from the client on passing the recaptchaKey.
      // recaptchaAction: Action name corresponding to the token.
      public void createAssessment(string projectID = "project-id", string recaptchaKey = "recaptcha-key",
          string token = "action-token", string recaptchaAction = "action-name")
      {

          // Create the client.
          // TODO: To avoid memory issues, move this client generation outside
          // of this example, and cache it (recommended) or call client.close()
          // before exiting this method.
          RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.Create();

          ProjectName projectName = new ProjectName(projectID);

          // Build the assessment request.
          CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
          {
              Assessment = new Assessment()
              {
                  // Set the properties of the event to be tracked.
                  Event = new Event()
                  {
                      SiteKey = recaptchaKey,
                      Token = token,
                      ExpectedAction = recaptchaAction
                  },
              },
              ParentAsProjectName = projectName
          };

          Assessment response = client.CreateAssessment(createAssessmentRequest);

          // Check if the token is valid.
          if (response.TokenProperties.Valid == false)
          {
              System.Console.WriteLine("The CreateAssessment call failed because the token was: " +
                  response.TokenProperties.InvalidReason.ToString());
              return;
          }

          // Check if the expected action was executed.
          if (response.TokenProperties.Action != recaptchaAction)
          {
              System.Console.WriteLine("The action attribute in reCAPTCHA tag is: " +
                  response.TokenProperties.Action.ToString());
              System.Console.WriteLine("The action attribute in the reCAPTCHA tag does not " +
                  "match the action you are expecting to score");
              return;
          }

          // Get the risk score and the reasons.
          // For more information on interpreting the assessment,
          // see: https://cloud.google.com/recaptcha/docs/interpret-assessment
          System.Console.WriteLine("The reCAPTCHA score is: " + ((decimal)response.RiskAnalysis.Score));

          foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons)
          {
              System.Console.WriteLine(reason.ToString());
          }
      }

      public static