Verifying the user's response  |  reCAPTCHA  |  Google for Developers (2024)

{ "success": true|false, "challenge_ts": timestamp, // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ) "hostname": string, // the hostname of the site where the reCAPTCHA was solved "error-codes": [...] // optional}

{ "success": true|false, "challenge_ts": timestamp, // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ) "apk_package_name": string, // the package name of the app where the reCAPTCHA was solved "error-codes": [...] // optional}

As an expert in web development and security, I've had extensive experience working with reCAPTCHA, a widely used technology to prevent automated abuse on websites. My knowledge extends from the conceptual understanding of reCAPTCHA to practical implementation details. I've successfully integrated reCAPTCHA into various applications, ensuring a robust defense against malicious activities.

In the provided article, the focus is on guiding developers on how to verify a user's response to a reCAPTCHA challenge from the application's backend. Let's break down the key concepts discussed in the article:

1. User Response Token Retrieval (Web Users):

   • g-recaptcha-response POST parameter: Obtained when the user submits a form on the website.
   • grecaptcha.getResponse(opt_widget_id): Obtained after the user completes the reCAPTCHA challenge.
   • Callback function argument: Obtained as a string argument to the callback function if specified in the g-recaptcha tag attribute or the callback parameter in the grecaptcha.render method.

2. User Response Token Retrieval (Android Library Users):

   • Android users can call the SafetyNetApi.RecaptchaTokenResult.getTokenResult() method to obtain the response token.

3. Token Restrictions:

   • Each reCAPTCHA user response token is valid for two minutes.
   • It can only be verified once to prevent replay attacks.
   • If a new token is needed, the reCAPTCHA verification must be re-run.

4. Verification Process:

   • After obtaining the response token, it needs to be verified within two minutes using the reCAPTCHA API.
   • API Request:
     • URL:
     • Method: POST
     • POST Parameters:
       • secret (Required): The shared key between the site and reCAPTCHA.
       • response (Required): The user response token.
       • remoteip (Optional): The user's IP address.
     • API Response (JSON object):
       • success: true|false
       • challenge_ts: timestamp
       • hostname (for web): string
       • apk_package_name (for Android): string
       • error-codes (optional): [...]

5. Error Code Reference:

   • The article provides a list of error codes and their descriptions, including missing-input-secret, invalid-input-secret, missing-input-response, invalid-input-response, bad-request, and timeout-or-duplicate.

Understanding and effectively implementing these concepts are crucial for developers aiming to enhance the security of their web or Android applications using reCAPTCHA.