Create assessments for mobile applications

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 (token), when the end user triggers an action.

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 on your iOS application or on your Android application.
  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:

Retrieve a token

Retrieve a token from the response of the execute() call.

You can access each user's token only once. If you need to assess a subsequent action that a user takes on your mobile application, 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