{"id":4025,"library":"google-cloud-recaptcha-enterprise","title":"Google Cloud reCAPTCHA Enterprise API client library","description":"The `google-cloud-recaptcha-enterprise` client library provides Python access to the Google Cloud reCAPTCHA Enterprise API. reCAPTCHA Enterprise protects websites and mobile applications from fraudulent activity, spam, and abuse by using advanced risk analysis and machine learning to distinguish between legitimate users and bots. The library is actively maintained as part of the `google-cloud-python` monorepo and is currently at version 1.31.0, with ongoing releases for features and bug fixes across the Google Cloud client libraries.","status":"active","version":"1.31.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-recaptcha-enterprise","tags":["google cloud","recaptcha","security","bot detection","fraud prevention"],"install":[{"cmd":"pip install google-cloud-recaptcha-enterprise","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"symbol":"RecaptchaEnterpriseServiceClient","correct":"from google.cloud import recaptchaenterprise_v1\nclient = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()"},{"note":"Used for creating request and response message types like `Event` and `Assessment`.","symbol":"types","correct":"from google.cloud.recaptchaenterprise_v1 import types"}],"quickstart":{"code":"import os\nfrom google.cloud import recaptchaenterprise_v1\nfrom google.cloud.recaptchaenterprise_v1 import types\n\ndef create_assessment_sample(\n    project_id: str,\n    site_key: str,\n    token: str,\n    action: str,\n    user_ip: str = None,\n    user_agent: str = None,\n) -> None:\n    \"\"\"Creates an assessment to analyze the risk of a UI action.\n\n    Args:\n        project_id: Your Google Cloud project ID.\n        site_key: The reCAPTCHA key associated with the site or app.\n        token: The user's response token for which you want to receive a reCAPTCHA score.\n        action: The user-initiated action that you specified for action in the grecaptcha.enterprise.execute() call.\n        user_ip: (Optional) The IP address of the user sending a request to your backend.\n        user_agent: (Optional) The user agent in the request from the user's device.\n    \"\"\"\n\n    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()\n\n    event = types.Event()\n    event.site_key = site_key\n    event.token = token\n    event.expected_action = action\n\n    if user_ip:\n        event.user_ip_address = user_ip\n    if user_agent:\n        event.user_agent = user_agent\n\n    assessment = types.Assessment()\n    assessment.event = event\n\n    project_name = client.project_path(project_id)\n\n    try:\n        response = client.create_assessment(parent=project_name, assessment=assessment)\n\n        # Check if the token is valid.\n        if not response.token_properties.valid:\n            print(\n                \"The create_assessment() call failed because the token was invalid with the following reason: \"\n                f\"{response.token_properties.invalid_reason}\"\n            )\n            return\n\n        # Check if the expected action was executed.\n        if response.token_properties.action == action:\n            # Get the risk score and the reason(s).\n            # For more information on interpreting the assessment,\n            # see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment\n            print(f\"The reCAPTCHA score for this token is: {response.risk_analysis.score}\")\n            for reason in response.risk_analysis.reasons:\n                print(f\"  Reason: {reason.name}\")\n        else:\n            print(\n                \"The action attribute in your reCAPTCHA tag does not match the action you are expecting to score.\" \n                f\"Expected: {action}, Actual: {response.token_properties.action}\"\n            )\n    except Exception as e:\n        print(f\"Error creating assessment: {e}\")\n\n# Example Usage (replace with your actual project_id, site_key, and token)\nif __name__ == \"__main__\":\n    project_id = os.environ.get('GOOGLE_CLOUD_PROJECT_ID', 'your-project-id')\n    # The site key generated for your reCAPTCHA Enterprise site/app\n    site_key = os.environ.get('RECAPTCHA_ENTERPRISE_SITE_KEY', 'your-site-key')\n    # The token obtained from the client-side reCAPTCHA execution\n    token = os.environ.get('RECAPTCHA_ENTERPRISE_TOKEN', 'your-recaptcha-token')\n    action = 'login'\n    user_ip = '192.0.2.1' # Example IP, use actual user's IP\n    user_agent = 'Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.5481.65 Mobile Safari/537.36'\n\n    if project_id == 'your-project-id' or site_key == 'your-site-key' or token == 'your-recaptcha-token':\n        print(\"Please set GOOGLE_CLOUD_PROJECT_ID, RECAPTCHA_ENTERPRISE_SITE_KEY, and RECAPTCHA_ENTERPRISE_TOKEN environment variables or replace placeholders in the script.\")\n    else:\n        create_assessment_sample(project_id, site_key, token, action, user_ip, user_agent)","lang":"python","description":"This quickstart demonstrates how to create an assessment using the reCAPTCHA Enterprise client library in Python. An assessment verifies the authenticity and risk score of a reCAPTCHA response token received from your frontend application. Ensure your Google Cloud project has the reCAPTCHA Enterprise API enabled, and you have configured authentication (e.g., Application Default Credentials) and created a reCAPTCHA site key."},"warnings":[{"fix":"Migrate your existing reCAPTCHA keys to a Google Cloud project via the Google Cloud Console. This process consolidates management and billing under Google Cloud.","message":"All classic reCAPTCHA keys must be migrated to a Google Cloud project by the end of 2025. Failure to migrate will result in keys becoming invalid and the service being unavailable.","severity":"breaking","affected_versions":"All versions using classic reCAPTCHA keys"},{"fix":"Restrict API keys by server IP addresses or keep them unrestricted for the `reCAPTCHA Enterprise API` service only.","message":"When creating API keys for backend reCAPTCHA Enterprise verification, avoid restricting the key by HTTP referrers. Such restrictions will silently block server-side requests, leading to verification failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Enable billing for your Google Cloud project to continue processing assessments beyond the free tier.","message":"The first 10,000 reCAPTCHA Enterprise assessments per month are free. Exceeding this quota without enabled billing will cause `create_assessment` requests to fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement a retry mechanism for `grecaptcha.enterprise.execute()` in your client-side JavaScript.","message":"The `BROWSER_ERROR` token response indicates a client-side network failure or timeout, not a backend issue.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your environment uses Python 3.9 or newer. Update to the latest supported Python version.","message":"Support for Python versions older than 3.9 has been dropped by various Google Cloud Python libraries in recent releases (e.g., pandas-gbq and bigquery-magics in the provided GitHub releases). While the `google-cloud-recaptcha-enterprise` PyPI metadata currently specifies `>=3.9`, older Python versions may lead to compatibility issues with other ecosystem libraries or future updates.","severity":"deprecated","affected_versions":"<= 3.8"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}