0
# Google Cloud reCAPTCHA Enterprise
1

2
Google Cloud reCAPTCHA Enterprise provides advanced protection for websites and applications against fraudulent activities including scraping, credential stuffing, automated account creation, and other malicious interactions. This enterprise-grade solution offers comprehensive fraud detection, assessment analysis, and configurable security policies with detailed metrics and analytics.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-recaptcha-enterprise
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-recaptcha-enterprise`
9
- **Python Support**: 3.7+
10
- **License**: Apache 2.0
11

12
## Core Imports
13

14
```python
15
from google.cloud import recaptchaenterprise
16
```
17

18
For direct v1 API access:
19

20
```python
21
from google.cloud import recaptchaenterprise_v1
22
```
23

24
For specific client classes:
25

26
```python
27
from google.cloud.recaptchaenterprise import RecaptchaEnterpriseServiceClient
28
from google.cloud.recaptchaenterprise import RecaptchaEnterpriseServiceAsyncClient
29
```
30

31
## Basic Usage
32

33
```python
34
from google.cloud import recaptchaenterprise
35
from google.cloud.recaptchaenterprise_v1.types import Assessment, Event
36

37
# Initialize the client
38
client = recaptchaenterprise.RecaptchaEnterpriseServiceClient()
39

40
# Create an assessment to analyze user interaction
41
project_path = f"projects/{project_id}"
42

43
# Create event details for assessment
44
event = Event(
45
    site_key=site_key,
46
    user_agent="Mozilla/5.0...",
47
    user_ip_address="192.168.1.1",
48
    expected_action="login"
49
)
50

51
# Create assessment request
52
assessment = Assessment(event=event)
53
request = recaptchaenterprise.CreateAssessmentRequest(
54
    parent=project_path,
55
    assessment=assessment
56
)
57

58
# Execute assessment
59
response = client.create_assessment(request=request)
60

61
# Analyze results
62
if response.risk_analysis.score > 0.5:
63
    print("User interaction appears legitimate")
64
    # Allow action
65
else:
66
    print("Potential fraud detected")
67
    # Block or challenge user
68
```
69

70
## Architecture
71

72
The reCAPTCHA Enterprise API follows Google Cloud's standard client library patterns with several key components:
73

74
- **Client Classes**: Synchronous (`RecaptchaEnterpriseServiceClient`) and asynchronous (`RecaptchaEnterpriseServiceAsyncClient`) interfaces
75
- **Assessment Engine**: Core fraud detection that analyzes user interactions and provides risk scores
76
- **Key Management**: Platform-specific reCAPTCHA keys for web, Android, and iOS applications
77
- **Firewall Policies**: Configurable rules for automated response to detected threats
78
- **Account Defender**: Advanced account protection analyzing user behavior patterns
79
- **Metrics & Analytics**: Comprehensive reporting on protection effectiveness and usage patterns
80

81
The client handles authentication, retries, and error management automatically while providing fine-grained control over security policies and threat responses.
82

83
## Capabilities
84

85
### Assessment Operations
86

87
Core fraud detection functionality that analyzes user interactions and provides risk scores, token validation, and detailed threat analysis including account defender assessments and fraud prevention signals.
88

89
```python { .api }
90
def create_assessment(request: CreateAssessmentRequest) -> Assessment: ...
91
def annotate_assessment(request: AnnotateAssessmentRequest) -> AnnotateAssessmentResponse: ...
92
```
93

94
[Assessment Operations](./assessment-operations.md)
95

96
### Key Management
97

98
Comprehensive management of reCAPTCHA keys for different platforms (web, Android, iOS) including creation, configuration, updates, deletion, and migration from legacy reCAPTCHA versions.
99

100
```python { .api }
101
def create_key(request: CreateKeyRequest) -> Key: ...
102
def list_keys(request: ListKeysRequest) -> ListKeysResponse: ...
103
def get_key(request: GetKeyRequest) -> Key: ...
104
def update_key(request: UpdateKeyRequest) -> Key: ...
105
def delete_key(request: DeleteKeyRequest) -> None: ...
106
def migrate_key(request: MigrateKeyRequest) -> Key: ...
107
def retrieve_legacy_secret_key(request: RetrieveLegacySecretKeyRequest) -> RetrieveLegacySecretKeyResponse: ...
108
```
109

110
[Key Management](./key-management.md)
111

112
### Firewall Policies
113

114
Advanced security rules that automatically respond to detected threats with configurable actions including allow, block, substitute, and redirect responses based on risk analysis and custom conditions.
115

116
```python { .api }
117
def create_firewall_policy(request: CreateFirewallPolicyRequest) -> FirewallPolicy: ...
118
def list_firewall_policies(request: ListFirewallPoliciesRequest) -> ListFirewallPoliciesResponse: ...
119
def get_firewall_policy(request: GetFirewallPolicyRequest) -> FirewallPolicy: ...
120
def update_firewall_policy(request: UpdateFirewallPolicyRequest) -> FirewallPolicy: ...
121
def delete_firewall_policy(request: DeleteFirewallPolicyRequest) -> None: ...
122
def reorder_firewall_policies(request: ReorderFirewallPoliciesRequest) -> ReorderFirewallPoliciesResponse: ...
123
```
124

125
[Firewall Policies](./firewall-policies.md)
126

127
### IP Override Management
128

129
Management of IP address overrides for testing and development environments, allowing specific IP addresses to be treated differently during reCAPTCHA assessments.
130

131
```python { .api }
132
def add_ip_override(request: AddIpOverrideRequest) -> AddIpOverrideResponse: ...
133
def remove_ip_override(request: RemoveIpOverrideRequest) -> RemoveIpOverrideResponse: ...
134
def list_ip_overrides(request: ListIpOverridesRequest) -> ListIpOverridesResponse: ...
135
```
136

137
[IP Override Management](./ip-override-management.md)
138

139
### Account Security Analysis
140

141
Advanced account protection features including related account group analysis, membership tracking, and search capabilities for detecting coordinated fraud attempts and abuse patterns.
142

143
```python { .api }
144
def list_related_account_groups(request: ListRelatedAccountGroupsRequest) -> ListRelatedAccountGroupsResponse: ...
145
def list_related_account_group_memberships(request: ListRelatedAccountGroupMembershipsRequest) -> ListRelatedAccountGroupMembershipsResponse: ...
146
def search_related_account_group_memberships(request: SearchRelatedAccountGroupMembershipsRequest) -> SearchRelatedAccountGroupMembershipsResponse: ...
147
```
148

149
[Account Security Analysis](./account-security-analysis.md)
150

151
### Metrics and Analytics
152

153
Comprehensive reporting and analytics for monitoring reCAPTCHA usage, effectiveness, performance metrics, score distributions, and challenge completion rates.
154

155
```python { .api }
156
def get_metrics(request: GetMetricsRequest) -> Metrics: ...
157
```
158

159
[Metrics and Analytics](./metrics-analytics.md)
160

161
## Core Types
162

163
### Assessment Types
164

165
```python { .api }
166
class Assessment:
167
    """Assessment of user interaction for fraud detection."""
168
    name: str
169
    event: Event
170
    risk_analysis: RiskAnalysis
171
    token_properties: TokenProperties
172
    account_defender_assessment: AccountDefenderAssessment
173
    fraud_prevention_assessment: FraudPreventionAssessment
174
    phone_fraud_assessment: PhoneFraudAssessment
175
    firewall_policy_assessment: FirewallPolicyAssessment
176

177
class Event:
178
    """User event details for assessment."""
179
    token: str
180
    site_key: str
181
    user_agent: str
182
    user_ip_address: str
183
    expected_action: str
184
    hashed_account_id: bytes
185
    express: bool
186
    requested_uri: str
187
    waf_token_assessment: bool
188
    ja3: str
189
    headers: List[str]
190
    firewall_policy_evaluation: bool
191

192
class RiskAnalysis:
193
    """Risk analysis results from assessment."""
194
    score: float
195
    reasons: List[str]
196
    extended_verdict: ExtendedVerdict
197

198
class TokenProperties:
199
    """Properties of the reCAPTCHA token."""
200
    valid: bool
201
    invalid_reason: str
202
    hostname: str
203
    android_package_name: str
204
    ios_bundle_id: str
205
    action: str
206
    create_time: Timestamp
207
```
208

209
### Key Management Types
210

211
```python { .api }
212
class Key:
213
    """reCAPTCHA key configuration."""
214
    name: str
215
    display_name: str
216
    web_settings: WebKeySettings
217
    android_settings: AndroidKeySettings
218
    ios_settings: IOSKeySettings
219
    labels: Dict[str, str]
220
    create_time: Timestamp
221
    testing_options: TestingOptions
222
    waf_settings: WafSettings
223

224
class WebKeySettings:
225
    """Settings for web-based keys."""
226
    allow_all_domains: bool
227
    allowed_domains: List[str]
228
    allow_amp_traffic: bool
229
    integration_type: str
230
    challenge_security_preference: str
231

232
class AndroidKeySettings:
233
    """Settings for Android app keys."""
234
    allow_all_package_names: bool
235
    allowed_package_names: List[str]
236
    support_non_google_app_store_distribution: bool
237

238
class IOSKeySettings:
239
    """Settings for iOS app keys."""
240
    allow_all_bundle_ids: bool
241
    allowed_bundle_ids: List[str]
242
    apple_developer_id: AppleDeveloperId
243
```
244

245
### Client Classes
246

247
```python { .api }
248
class RecaptchaEnterpriseServiceClient:
249
    """Synchronous client for reCAPTCHA Enterprise API operations."""
250
    def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
251
    def create_assessment(self, request=None, **kwargs) -> Assessment: ...
252
    def annotate_assessment(self, request=None, **kwargs) -> AnnotateAssessmentResponse: ...
253
    # ... all other synchronous API methods
254

255
class RecaptchaEnterpriseServiceAsyncClient:
256
    """Asynchronous client for reCAPTCHA Enterprise API operations."""  
257
    def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
258
    async def create_assessment(self, request=None, **kwargs) -> Assessment: ...
259
    async def annotate_assessment(self, request=None, **kwargs) -> AnnotateAssessmentResponse: ...
260
    # ... all other asynchronous API methods
261
```
262

263
### Firewall Types
264

265
```python { .api }
266
class FirewallPolicy:
267
    """Firewall policy configuration."""
268
    name: str
269
    description: str
270
    path: str
271
    condition: str
272
    actions: List[FirewallAction]
273

274
class FirewallAction:
275
    """Action to take when firewall conditions match."""
276
    allow: AllowAction
277
    block: BlockAction
278
    substitute: SubstituteAction
279
    redirect: RedirectAction
280
    set_header: SetHeaderAction
281
```
282

283
### Google Protobuf Types
284

285
```python { .api }
286
class Timestamp:
287
    """Google protobuf timestamp type for representing time."""
288
    seconds: int      # Seconds since Unix epoch
289
    nanos: int        # Nanoseconds within the second
290

291
class FieldMask:
292
    """Google protobuf field mask for specifying fields to update."""
293
    paths: List[str]  # Field paths in dot notation (e.g., "display_name", "web_settings.allowed_domains")
294
```
295

296
## Authentication and Configuration
297

298
The client supports standard Google Cloud authentication patterns:
299

300
- **Application Default Credentials (ADC)**: Automatically detects credentials from environment
301
- **Service Account Keys**: JSON key files for service accounts
302
- **OAuth 2.0**: For user-based authentication flows
303

304
```python
305
# Using Application Default Credentials
306
client = recaptchaenterprise.RecaptchaEnterpriseServiceClient()
307

308
# Using service account key file
309
from google.oauth2 import service_account
310
credentials = service_account.Credentials.from_service_account_file(
311
    "/path/to/service-account-key.json"
312
)
313
client = recaptchaenterprise.RecaptchaEnterpriseServiceClient(credentials=credentials)
314

315
# Custom endpoint configuration
316
client = recaptchaenterprise.RecaptchaEnterpriseServiceClient(
317
    client_options={"api_endpoint": "https://custom-endpoint.googleapis.com"}
318
)
319
```
320

321
## Error Handling
322

323
The library integrates with Google API Core for comprehensive error handling:
324

325
```python
326
from google.api_core import exceptions
327

328
try:
329
    response = client.create_assessment(request=request)
330
except exceptions.GoogleAPICallError as e:
331
    print(f"API call failed: {e}")
332
except exceptions.InvalidArgument as e:
333
    print(f"Invalid request parameters: {e}")
334
except exceptions.PermissionDenied as e:
335
    print(f"Insufficient permissions: {e}")
336
```
337

338
Common exceptions include:
339
- `InvalidArgument`: Malformed request parameters
340
- `PermissionDenied`: Insufficient IAM permissions
341
- `NotFound`: Requested resource doesn't exist
342
- `AlreadyExists`: Resource creation conflicts
343
- `ResourceExhausted`: Rate limits or quotas exceeded