Package google.cloud.recaptchaenterprise.v1

Index

RecaptchaEnterpriseService

Service to determine the likelihood an event is legitimate.

AddIpOverride

rpc AddIpOverride(AddIpOverrideRequest) returns (AddIpOverrideResponse)

Adds an IP override to a key. The following restrictions hold: * The maximum number of IP overrides per key is 100. * For any conflict (such as IP already exists or IP part of an existing IP range), an error is returned.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.keys.update

For more information, see the IAM documentation.

AnnotateAssessment

rpc AnnotateAssessment(AnnotateAssessmentRequest) returns (AnnotateAssessmentResponse)

Annotates a previously created Assessment to provide additional information on whether the event turned out to be authentic or fraudulent.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.assessments.annotate

For more information, see the IAM documentation.

CreateAssessment

rpc CreateAssessment(CreateAssessmentRequest) returns (Assessment)

Creates an Assessment of the likelihood an event is legitimate.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.assessments.create

For more information, see the IAM documentation.

CreateFirewallPolicy

rpc CreateFirewallPolicy(CreateFirewallPolicyRequest) returns (FirewallPolicy)

Creates a new FirewallPolicy, specifying conditions at which reCAPTCHA Enterprise actions can be executed. A project may have a maximum of 1000 policies.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.firewallpolicies.create

For more information, see the IAM documentation.

CreateKey

rpc CreateKey(CreateKeyRequest) returns (Key)

Creates a new reCAPTCHA Enterprise key.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.keys.create

For more information, see the IAM documentation.

DeleteFirewallPolicy

rpc DeleteFirewallPolicy(DeleteFirewallPolicyRequest) returns (Empty)

Deletes the specified firewall policy.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.firewallpolicies.delete

For more information, see the IAM documentation.

DeleteKey

rpc DeleteKey(DeleteKeyRequest) returns (Empty)

Deletes the specified key.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.keys.delete

For more information, see the IAM documentation.

GetFirewallPolicy

rpc GetFirewallPolicy(GetFirewallPolicyRequest) returns (FirewallPolicy)

Returns the specified firewall policy.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.firewallpolicies.get

For more information, see the IAM documentation.

GetKey

rpc GetKey(GetKeyRequest) returns (Key)

Returns the specified key.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.keys.get

For more information, see the IAM documentation.

GetMetrics

rpc GetMetrics(GetMetricsRequest) returns (Metrics)

Get some aggregated metrics for a Key. This data can be used to build dashboards.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.metrics.get

For more information, see the IAM documentation.

ListFirewallPolicies

rpc ListFirewallPolicies(ListFirewallPoliciesRequest) returns (ListFirewallPoliciesResponse)

Returns the list of all firewall policies that belong to a project.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.firewallpolicies.list

For more information, see the IAM documentation.

ListIpOverrides

rpc ListIpOverrides(ListIpOverridesRequest) returns (ListIpOverridesResponse)

Lists all IP overrides for a key.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.keys.get

For more information, see the IAM documentation.

ListKeys

rpc ListKeys(ListKeysRequest) returns (ListKeysResponse)

Returns the list of all keys that belong to a project.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.keys.list

For more information, see the IAM documentation.

ListRelatedAccountGroupMemberships

rpc ListRelatedAccountGroupMemberships(ListRelatedAccountGroupMembershipsRequest) returns (ListRelatedAccountGroupMembershipsResponse)

Get memberships in a group of related accounts.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.relatedaccountgroupmemberships.list

For more information, see the IAM documentation.

ListRelatedAccountGroups

rpc ListRelatedAccountGroups(ListRelatedAccountGroupsRequest) returns (ListRelatedAccountGroupsResponse)

List groups of related accounts.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.relatedaccountgroups.list

For more information, see the IAM documentation.

MigrateKey

rpc MigrateKey(MigrateKeyRequest) returns (Key)

Migrates an existing key from reCAPTCHA to reCAPTCHA Enterprise. Once a key is migrated, it can be used from either product. SiteVerify requests are billed as CreateAssessment calls. You must be authenticated as one of the current owners of the reCAPTCHA Key, and your user must have the reCAPTCHA Enterprise Admin IAM role in the destination project.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.keys.update

For more information, see the IAM documentation.

RemoveIpOverride

rpc RemoveIpOverride(RemoveIpOverrideRequest) returns (RemoveIpOverrideResponse)

Removes an IP override from a key. The following restrictions hold: * If the IP isn't found in an existing IP override, a NOT_FOUND error is returned. * If the IP is found in an existing IP override, but the override type does not match, a NOT_FOUND error is returned.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.keys.update

For more information, see the IAM documentation.

ReorderFirewallPolicies

rpc ReorderFirewallPolicies(ReorderFirewallPoliciesRequest) returns (ReorderFirewallPoliciesResponse)

Reorders all firewall policies.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • recaptchaenterprise.firewallpolicies.update

For more information, see the IAM documentation.

RetrieveLegacySecretKey

rpc RetrieveLegacySecretKey(RetrieveLegacySecretKeyRequest) returns (RetrieveLegacySecretKeyResponse)

Returns the secret key related to the specified public key. You must use the legacy secret key only in a 3rd party integration with legacy reCAPTCHA.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the key resource:

  • recaptchaenterprise.keys.retrievelegacysecretkey

For more information, see the IAM documentation.

SearchRelatedAccountGroupMemberships

rpc SearchRelatedAccountGroupMemberships(SearchRelatedAccountGroupMembershipsRequest) returns (SearchRelatedAccountGroupMembershipsResponse)

Search group memberships related to a given account.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the project resource:

  • recaptchaenterprise.relatedaccountgroupmemberships.list

For more information, see the IAM documentation.

UpdateFirewallPolicy

rpc UpdateFirewallPolicy(UpdateFirewallPolicyRequest) returns (FirewallPolicy)

Updates the specified firewall policy.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.firewallpolicies.update

For more information, see the IAM documentation.

UpdateKey

rpc UpdateKey(UpdateKeyRequest) returns (Key)

Updates the specified key.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.keys.update

For more information, see the IAM documentation.

AccountDefenderAssessment

Account defender risk assessment.

Fields
labels[]

AccountDefenderLabel

Output only. Labels for this request.

AccountDefenderLabel

Labels returned by account defender for this request.

Enums
ACCOUNT_DEFENDER_LABEL_UNSPECIFIED Default unspecified type.
PROFILE_MATCH The request matches a known good profile for the user.
SUSPICIOUS_LOGIN_ACTIVITY The request is potentially a suspicious login event and must be further verified either through multi-factor authentication or another system.
SUSPICIOUS_ACCOUNT_CREATION The request matched a profile that previously had suspicious account creation behavior. This can mean that this is a fake account.
RELATED_ACCOUNTS_NUMBER_HIGH The account in the request has a high number of related accounts. It does not necessarily imply that the account is bad but can require further investigation.

AccountVerificationInfo

Information about account verification, used for identity verification.

Fields
endpoints[]

EndpointVerificationInfo

Optional. Endpoints that can be used for identity verification.

language_code

string

Optional. Language code preference for the verification message, set as a IETF BCP 47 language code.

latest_verification_result

Result

Output only. Result of the latest account verification challenge.

username
(deprecated)

string

Username of the account that is being verified. Deprecated. Customers should now provide the account_id field in event.user_info.

Result

Result of the account verification as contained in the verdict token issued at the end of the verification flow.

Enums
RESULT_UNSPECIFIED No information about the latest account verification.
SUCCESS_USER_VERIFIED The user was successfully verified. This means the account verification challenge was successfully completed.
ERROR_USER_NOT_VERIFIED The user failed the verification challenge.
ERROR_SITE_ONBOARDING_INCOMPLETE The site is not properly onboarded to use the account verification feature.
ERROR_RECIPIENT_NOT_ALLOWED The recipient is not allowed for account verification. This can occur during integration but should not occur in production.
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED The recipient has already been sent too many verification codes in a short amount of time.
ERROR_CRITICAL_INTERNAL The verification flow could not be completed due to a critical internal error.
ERROR_CUSTOMER_QUOTA_EXHAUSTED The client has exceeded their two factor request quota for this period of time.
ERROR_VERIFICATION_BYPASSED The request cannot be processed at the time because of an incident. This bypass can be restricted to a problematic destination email domain, a customer, or could affect the entire service.
ERROR_VERDICT_MISMATCH The request parameters do not match with the token provided and cannot be processed.

AddIpOverrideRequest

The AddIpOverride request message.

Fields
name

string

Required. The name of the key to which the IP override is added, in the format projects/{project}/keys/{key}.

ip_override_data

IpOverrideData

Required. IP override added to the key.

AddIpOverrideResponse

This type has no fields.

Response for AddIpOverride.

AndroidKeySettings

Settings specific to keys that can be used by Android apps.

Fields
allow_all_package_names

bool

Optional. If set to true, allowed_package_names are not enforced.

allowed_package_names[]

string

Optional. Android package names of apps allowed to use the key. Example: 'com.companyname.appname'

support_non_google_app_store_distribution

bool

Optional. Set to true for keys that are used in an Android application that is available for download in app stores in addition to the Google Play Store.

AnnotateAssessmentRequest

The request message to annotate an Assessment.

Fields
name

string

Required. The resource name of the Assessment, in the format projects/{project}/assessments/{assessment}.

annotation

Annotation

Optional. The annotation that is assigned to the Event. This field can be left empty to provide reasons that apply to an event without concluding whether the event is legitimate or fraudulent.

reasons[]

Reason

Optional. Reasons for the annotation that are assigned to the event.

account_id

string

Optional. A stable account identifier to apply to the assessment. This is an alternative to setting account_id in CreateAssessment, for example when a stable account identifier is not yet known in the initial request.

hashed_account_id

bytes

Optional. A stable hashed account identifier to apply to the assessment. This is an alternative to setting hashed_account_id in CreateAssessment, for example when a stable account identifier is not yet known in the initial request.

transaction_event

TransactionEvent

Optional. If the assessment is part of a payment transaction, provide details on payment lifecycle events that occur in the transaction.

Annotation

Enum that represents the types of annotations.

Enums
ANNOTATION_UNSPECIFIED Default unspecified type.
LEGITIMATE Provides information that the event turned out to be legitimate.
FRAUDULENT Provides information that the event turned out to be fraudulent.
PASSWORD_CORRECT

Provides information that the event was related to a login event in which the user typed the correct password. Deprecated, prefer indicating CORRECT_PASSWORD through the reasons field instead.

PASSWORD_INCORRECT

Provides information that the event was related to a login event in which the user typed the incorrect password. Deprecated, prefer indicating INCORRECT_PASSWORD through the reasons field instead.

Reason

Enum that represents potential reasons for annotating an assessment.

Enums
REASON_UNSPECIFIED Default unspecified reason.
CHARGEBACK Indicates that the transaction had a chargeback issued with no other details. When possible, specify the type by using CHARGEBACK_FRAUD or CHARGEBACK_DISPUTE instead.
CHARGEBACK_FRAUD Indicates that the transaction had a chargeback issued related to an alleged unauthorized transaction from the cardholder's perspective (for example, the card number was stolen).
CHARGEBACK_DISPUTE Indicates that the transaction had a chargeback issued related to the cardholder having provided their card details but allegedly not being satisfied with the purchase (for example, misrepresentation, attempted cancellation).
REFUND Indicates that the completed payment transaction was refunded by the seller.
REFUND_FRAUD Indicates that the completed payment transaction was determined to be fraudulent by the seller, and was cancelled and refunded as a result.
TRANSACTION_ACCEPTED Indicates that the payment transaction was accepted, and the user was charged.
TRANSACTION_DECLINED Indicates that the payment transaction was declined, for example due to invalid card details.
PAYMENT_HEURISTICS Indicates the transaction associated with the assessment is suspected of being fraudulent based on the payment method, billing details, shipping address or other transaction information.
INITIATED_TWO_FACTOR Indicates that the user was served a 2FA challenge. An old assessment with ENUM_VALUES.INITIATED_TWO_FACTOR reason that has not been overwritten with PASSED_TWO_FACTOR is treated as an abandoned 2FA flow. This is equivalent to FAILED_TWO_FACTOR.
PASSED_TWO_FACTOR Indicates that the user passed a 2FA challenge.
FAILED_TWO_FACTOR Indicates that the user failed a 2FA challenge.
CORRECT_PASSWORD Indicates the user provided the correct password.
INCORRECT_PASSWORD Indicates the user provided an incorrect password.
SOCIAL_SPAM Indicates that the user sent unwanted and abusive messages to other users of the platform, such as spam, scams, phishing, or social engineering.

AnnotateAssessmentResponse

This type has no fields.

Empty response for AnnotateAssessment.

AppleDeveloperId

Contains fields that are required to perform Apple-specific integrity checks.

Fields
private_key

string

Required. Input only. A private key (downloaded as a text file with a .p8 file extension) generated for your Apple Developer account. Ensure that Apple DeviceCheck is enabled for the private key.

key_id

string

Required. The Apple developer key ID (10-character string).

team_id

string

Required. The Apple team ID (10-character string) owning the provisioning profile used to build your application.

Assessment

A reCAPTCHA Enterprise assessment resource.

Fields
name

string

Output only. Identifier. The resource name for the Assessment in the format projects/{project}/assessments/{assessment}.

event

Event

Optional. The event being assessed.

risk_analysis

RiskAnalysis

Output only. The risk analysis result for the event being assessed.

token_properties

TokenProperties

Output only. Properties of the provided event token.

account_verification

AccountVerificationInfo

Optional. Account verification information for identity verification. The assessment event must include a token and site key to use this feature.

account_defender_assessment

AccountDefenderAssessment

Output only. Assessment returned by account defender when an account identifier is provided.

private_password_leak_verification

PrivatePasswordLeakVerification

Optional. The private password leak verification field contains the parameters that are used to to check for leaks privately without sharing user credentials.

firewall_policy_assessment

FirewallPolicyAssessment

Output only. Assessment returned when firewall policies belonging to the project are evaluated using the field firewall_policy_evaluation.

fraud_prevention_assessment

FraudPreventionAssessment

Output only. Assessment returned by Fraud Prevention when TransactionData is provided.

fraud_signals

FraudSignals

Output only. Fraud Signals specific to the users involved in a payment transaction.

phone_fraud_assessment

PhoneFraudAssessment

Output only. Assessment returned when a site key, a token, and a phone number as user_id are provided. Account defender and SMS toll fraud protection need to be enabled.

assessment_environment

AssessmentEnvironment

Optional. The environment creating the assessment. This describes your environment (the system invoking CreateAssessment), NOT the environment of your user.

AssessmentEnvironment

The environment creating the assessment. This describes your environment (the system invoking CreateAssessment), NOT the environment of your user.

Fields
client

string

Optional. Identifies the client module initiating the CreateAssessment request. This can be the link to the client module's project. Examples include: - "github.com/GoogleCloudPlatform/recaptcha-enterprise-google-tag-manager" - "cloud.google.com/recaptcha/docs/implement-waf-akamai" - "cloud.google.com/recaptcha/docs/implement-waf-cloudflare" - "wordpress.org/plugins/recaptcha-something"

version

string

Optional. The version of the client module. For example, "1.0.0".

ChallengeMetrics

Metrics related to challenges.

Fields
pageload_count

int64

Count of reCAPTCHA checkboxes or badges rendered. This is mostly equivalent to a count of pageloads for pages that include reCAPTCHA.

nocaptcha_count

int64

Count of nocaptchas (successful verification without a challenge) issued.

failed_count

int64

Count of submitted challenge solutions that were incorrect or otherwise deemed suspicious such that a subsequent challenge was triggered.

passed_count

int64

Count of nocaptchas (successful verification without a challenge) plus submitted challenge solutions that were correct and resulted in verification.

CreateAssessmentRequest

The create assessment request message.

Fields
parent

string

Required. The name of the project in which the assessment is created, in the format projects/{project}.

assessment

Assessment

Required. The assessment details.

CreateFirewallPolicyRequest

The create firewall policy request message.

Fields
parent

string

Required. The name of the project this policy applies to, in the format projects/{project}.

firewall_policy

FirewallPolicy

Required. Information to create the policy.

CreateKeyRequest

The create key request message.

Fields
parent

string

Required. The name of the project in which the key is created, in the format projects/{project}.

key

Key

Required. Information to create a reCAPTCHA Enterprise key.

DeleteFirewallPolicyRequest

The delete firewall policy request message.

Fields
name

string

Required. The name of the policy to be deleted, in the format projects/{project}/firewallpolicies/{firewallpolicy}.

DeleteKeyRequest

The delete key request message.

Fields
name

string

Required. The name of the key to be deleted, in the format projects/{project}/keys/{key}.

EndpointVerificationInfo

Information about a verification endpoint that can be used for 2FA.

Fields
request_token

string

Output only. Token to provide to the client to trigger endpoint verification. It must be used within 15 minutes.

last_verification_time

Timestamp

Output only. Timestamp of the last successful verification for the endpoint, if any.

Union field endpoint.

endpoint can be only one of the following:

email_address

string

Email address for which to trigger a verification request.

phone_number

string

Phone number for which to trigger a verification request. Should be given in E.164 format.

Event

The event being assessed.

Fields
token

string

Optional. The user response token provided by the reCAPTCHA Enterprise client-side integration on your site.

site_key

string

Optional. The site key that was used to invoke reCAPTCHA Enterprise on your site and generate the token.

user_agent

string

Optional. The user agent present in the request from the user's device related to this event.

user_ip_address

string

Optional. The IP address in the request from the user's device related to this event.

expected_action

string

Optional. The expected action for this type of event. This should be the same action provided at token generation time on client-side platforms already integrated with recaptcha enterprise.

hashed_account_id
(deprecated)

bytes

Optional. Deprecated: use user_info.account_id instead. Unique stable hashed user identifier for the request. The identifier must be hashed using hmac-sha256 with stable secret.

express

bool

Optional. Flag for a reCAPTCHA express request for an assessment without a token. If enabled, site_key must reference an Express site key.

requested_uri

string

Optional. The URI resource the user requested that triggered an assessment.

waf_token_assessment

bool

Optional. Flag for running WAF token assessment. If enabled, the token must be specified, and have been created by a WAF-enabled key.

ja3

string

Optional. JA3 fingerprint for SSL clients.

headers[]

string

Optional. HTTP header information about the request.

firewall_policy_evaluation

bool

Optional. Flag for enabling firewall policy config assessment. If this flag is enabled, the firewall policy is evaluated and a suggested firewall action is returned in the response.

transaction_data

TransactionData

Optional. Data describing a payment transaction to be assessed. Sending this data enables reCAPTCHA Enterprise Fraud Prevention and the FraudPreventionAssessment component in the response.

user_info

UserInfo

Optional. Information about the user that generates this event, when they can be identified. They are often identified through the use of an account for logged-in requests or login/registration requests, or by providing user identifiers for guest actions like checkout.

fraud_prevention

FraudPrevention

Optional. The Fraud Prevention setting for this assessment.

FraudPrevention

Setting that controls Fraud Prevention assessments.

Enums
FRAUD_PREVENTION_UNSPECIFIED Default, unspecified setting. If opted in for automatic detection, fraud_prevention_assessment is returned based on the request. Otherwise, fraud_prevention_assessment is returned if transaction_data is present in the Event and Fraud Prevention is enabled in the Google Cloud console.
ENABLED Enable Fraud Prevention for this assessment, if Fraud Prevention is enabled in the Google Cloud console.
DISABLED Disable Fraud Prevention for this assessment, regardless of opt-in status or Google Cloud console settings.

ExpressKeySettings

This type has no fields.

Settings specific to keys that can be used for reCAPTCHA Express.

FirewallAction

An individual action. Each action represents what to do if a policy matches.

Fields

Union field firewall_action_oneof.

firewall_action_oneof can be only one of the following:

allow

AllowAction

The user request did not match any policy and should be allowed access to the requested resource.

block

BlockAction

This action denies access to a given page. The user gets an HTTP error code.

include_recaptcha_script

IncludeRecaptchaScriptAction

This action injects reCAPTCHA JavaScript code into the HTML page returned by the site backend.

redirect

RedirectAction

This action redirects the request to a reCAPTCHA interstitial to attach a token.

substitute

SubstituteAction

This action transparently serves a different page to an offending user.

set_header

SetHeaderAction

This action sets a custom header but allow the request to continue to the customer backend.

AllowAction

This type has no fields.

An allow action continues processing a request unimpeded.

BlockAction

This type has no fields.

A block action serves an HTTP error code a prevents the request from hitting the backend.

IncludeRecaptchaScriptAction

This type has no fields.

An include reCAPTCHA script action involves injecting reCAPTCHA JavaScript code into the HTML returned by the site backend. This reCAPTCHA script is tasked with collecting user signals on the requested web page, issuing tokens as a cookie within the site domain, and enabling their utilization in subsequent page requests.

RedirectAction

This type has no fields.

A redirect action returns a 307 (temporary redirect) response, pointing the user to a reCAPTCHA interstitial page to attach a token.

SetHeaderAction

A set header action sets a header and forwards the request to the backend. This can be used to trigger custom protection implemented on the backend.

Fields
key

string

Optional. The header key to set in the request to the backend server.

value

string

Optional. The header value to set in the request to the backend server.

SubstituteAction

A substitute action transparently serves a different page than the one requested.

Fields
path

string

Optional. The address to redirect to. The target is a relative path in the current host. Example: "/blog/404.html".

FirewallPolicy

A FirewallPolicy represents a single matching pattern and resulting actions to take.

Fields
name

string

Identifier. The resource name for the FirewallPolicy in the format projects/{project}/firewallpolicies/{firewallpolicy}.

description

string

Optional. A description of what this policy aims to achieve, for convenience purposes. The description can at most include 256 UTF-8 characters.

path

string

Optional. The path for which this policy applies, specified as a glob pattern. For more information on glob, see the manual page. A path has a max length of 200 characters.

condition

string

Optional. A CEL (Common Expression Language) conditional expression that specifies if this policy applies to an incoming user request. If this condition evaluates to true and the requested path matched the path pattern, the associated actions should be executed by the caller. The condition string is checked for CEL syntax correctness on creation. For more information, see the CEL spec and its language definition. A condition has a max length of 500 characters.

actions[]

FirewallAction

Optional. The actions that the caller should take regarding user access. There should be at most one terminal action. A terminal action is any action that forces a response, such as AllowAction, BlockAction or SubstituteAction. Zero or more non-terminal actions such as SetHeader might be specified. A single policy can contain up to 16 actions.

FirewallPolicyAssessment

Policy config assessment.

Fields
error

Status

Output only. If the processing of a policy config fails, an error is populated and the firewall_policy is left empty.

firewall_policy

FirewallPolicy

Output only. The policy that matched the request. If more than one policy may match, this is the first match. If no policy matches the incoming request, the policy field is left empty.

FraudPreventionAssessment

Assessment for Fraud Prevention.

Fields
transaction_risk

float

Output only. Probability of this transaction being fraudulent. Summarizes the combined risk of attack vectors below. Values are from 0.0 (lowest) to 1.0 (highest).

stolen_instrument_verdict

StolenInstrumentVerdict

Output only. Assessment of this transaction for risk of a stolen instrument.

card_testing_verdict

CardTestingVerdict

Output only. Assessment of this transaction for risk of being part of a card testing attack.

behavioral_trust_verdict

BehavioralTrustVerdict

Output only. Assessment of this transaction for behavioral trust.

BehavioralTrustVerdict

Information about behavioral trust of the transaction.

Fields
trust

float

Output only. Probability of this transaction attempt being executed in a behaviorally trustworthy way. Values are from 0.0 (lowest) to 1.0 (highest).

CardTestingVerdict

Information about card testing fraud, where an adversary is testing fraudulently obtained cards or brute forcing their details.

Fields
risk

float

Output only. Probability of this transaction attempt being part of a card testing attack. Values are from 0.0 (lowest) to 1.0 (highest).

StolenInstrumentVerdict

Information about stolen instrument fraud, where the user is not the legitimate owner of the instrument being used for the purchase.

Fields
risk

float

Output only. Probability of this transaction being executed with a stolen instrument. Values are from 0.0 (lowest) to 1.0 (highest).

FraudSignals

Fraud signals describing users and cards involved in the transaction.

Fields
user_signals

UserSignals

Output only. Signals describing the end user in this transaction.

card_signals

CardSignals

Output only. Signals describing the payment card or cards used in this transaction.

CardSignals

Signals describing the payment card used in this transaction.

Fields
card_labels[]

CardLabel

Output only. The labels for the payment card in this transaction.

CardLabel

Risk labels describing the card being assessed, such as its funding mechanism.

Enums
CARD_LABEL_UNSPECIFIED No label specified.
PREPAID This card has been detected as prepaid.
VIRTUAL This card has been detected as virtual, such as a card number generated for a single transaction or merchant.
UNEXPECTED_LOCATION This card has been detected as being used in an unexpected geographic location.

UserSignals

Signals describing the user involved in this transaction.

Fields
active_days_lower_bound

int32

Output only. This user (based on email, phone, and other identifiers) has been seen on the internet for at least this number of days.

synthetic_risk

float

Output only. Likelihood (from 0.0 to 1.0) this user includes synthetic components in their identity, such as a randomly generated email address, temporary phone number, or fake shipping address.

GetFirewallPolicyRequest

The get firewall policy request message.

Fields
name

string

Required. The name of the requested policy, in the format projects/{project}/firewallpolicies/{firewallpolicy}.

GetKeyRequest

The get key request message.

Fields
name

string

Required. The name of the requested key, in the format projects/{project}/keys/{key}.

GetMetricsRequest

The get metrics request message.

Fields
name

string

Required. The name of the requested metrics, in the format projects/{project}/keys/{key}/metrics.

IOSKeySettings

Settings specific to keys that can be used by iOS apps.

Fields
allow_all_bundle_ids

bool

Optional. If set to true, allowed_bundle_ids are not enforced.

allowed_bundle_ids[]

string

Optional. iOS bundle ids of apps allowed to use the key. Example: 'com.companyname.productname.appname'

apple_developer_id

AppleDeveloperId

Optional. Apple Developer account details for the app that is protected by the reCAPTCHA Key. reCAPTCHA leverages platform-specific checks like Apple App Attest and Apple DeviceCheck to protect your app from abuse. Providing these fields allows reCAPTCHA to get a better assessment of the integrity of your app.

IpOverrideData

Information about the IP or IP range override.

Fields
ip

string

Required. The IP address to override (can be IPv4, IPv6 or CIDR). The IP override must be a valid IPv4 or IPv6 address, or a CIDR range. The IP override must be a public IP address. Example of IPv4: 168.192.5.6 Example of IPv6: 2001:0000:130F:0000:0000:09C0:876A:130B Example of IPv4 with CIDR: 168.192.5.0/24 Example of IPv6 with CIDR: 2001:0DB8:1234::/48

override_type

OverrideType

Required. Describes the type of IP override.

OverrideType

Enum that represents the type of IP override.

Enums
OVERRIDE_TYPE_UNSPECIFIED Default override type that indicates this enum hasn't been specified.
ALLOW Allowlist the IP address; i.e. give a risk_analysis.score of 0.9 for all valid assessments.

Key

A key used to identify and configure applications (web and/or mobile) that use reCAPTCHA Enterprise.

Fields
name

string

Identifier. The resource name for the Key in the format projects/{project}/keys/{key}.

display_name

string

Required. Human-readable display name of this key. Modifiable by user.

labels

map<string, string>

Optional. See Creating and managing labels.

create_time

Timestamp

Output only. The timestamp corresponding to the creation of this key.

testing_options

TestingOptions

Optional. Options for user acceptance testing.

waf_settings

WafSettings

Optional. Settings for WAF

Union field platform_settings. Platform-specific settings for this key. The key can only be used on a platform for which the settings are enabled. platform_settings can be only one of the following:
web_settings

WebKeySettings

Settings for keys that can be used by websites.

android_settings

AndroidKeySettings

Settings for keys that can be used by Android apps.

ios_settings

IOSKeySettings

Settings for keys that can be used by iOS apps.

express_settings

ExpressKeySettings

Settings for keys that can be used by reCAPTCHA Express.

ListFirewallPoliciesRequest

The list firewall policies request message.

Fields
parent

string

Required. The name of the project to list the policies for, in the format projects/{project}.

page_size

int32

Optional. The maximum number of policies to return. Default is 10. Max limit is 1000.

page_token

string

Optional. The next_page_token value returned from a previous. ListFirewallPoliciesRequest, if any.

ListFirewallPoliciesResponse

Response to request to list firewall policies belonging to a project.

Fields
firewall_policies[]

FirewallPolicy

Policy details.

next_page_token

string

Token to retrieve the next page of results. It is set to empty if no policies remain in results.

ListIpOverridesRequest

The ListIpOverrides request message.

Fields
parent

string

Required. The parent key for which the IP overrides are listed, in the format projects/{project}/keys/{key}.

page_size

int32

Optional. The maximum number of overrides to return. Default is 10. Max limit is 100. If the number of overrides is less than the page_size, all overrides are returned. If the page size is more than 100, it is coerced to 100.

page_token

string

Optional. The next_page_token value returned from a previous ListIpOverridesRequest, if any.

ListIpOverridesResponse

Response for ListIpOverrides.

Fields
ip_overrides[]

IpOverrideData

IP Overrides details.

next_page_token

string

Token to retrieve the next page of results. If this field is empty, no keys remain in the results.

ListKeysRequest

The list keys request message.

Fields
parent

string

Required. The name of the project that contains the keys that is listed, in the format projects/{project}.

page_size

int32

Optional. The maximum number of keys to return. Default is 10. Max limit is 1000.

page_token

string

Optional. The next_page_token value returned from a previous. ListKeysRequest, if any.

ListKeysResponse

Response to request to list keys in a project.

Fields
keys[]

Key

Key details.

next_page_token

string

Token to retrieve the next page of results. It is set to empty if no keys remain in results.

ListRelatedAccountGroupMembershipsRequest

The request message to list memberships in a related account group.

Fields
parent

string

Required. The resource name for the related account group in the format projects/{project}/relatedaccountgroups/{relatedaccountgroup}.

page_size

int32

Optional. The maximum number of accounts to return. The service might return fewer than this value. If unspecified, at most 50 accounts are returned. The maximum value is 1000; values above 1000 are coerced to 1000.

page_token

string

Optional. A page token, received from a previous ListRelatedAccountGroupMemberships call.

When paginating, all other parameters provided to ListRelatedAccountGroupMemberships must match the call that provided the page token.

ListRelatedAccountGroupMembershipsResponse

The response to a ListRelatedAccountGroupMemberships call.

Fields
related_account_group_memberships[]

RelatedAccountGroupMembership

The memberships listed by the query.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

ListRelatedAccountGroupsRequest

The request message to list related account groups.

Fields
parent

string

Required. The name of the project to list related account groups from, in the format projects/{project}.

page_size

int32

Optional. The maximum number of groups to return. The service might return fewer than this value. If unspecified, at most 50 groups are returned. The maximum value is 1000; values above 1000 are coerced to 1000.

page_token

string

Optional. A page token, received from a previous ListRelatedAccountGroups call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListRelatedAccountGroups must match the call that provided the page token.

ListRelatedAccountGroupsResponse

The response to a ListRelatedAccountGroups call.

Fields
related_account_groups[]

RelatedAccountGroup

The groups of related accounts listed by the query.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

Metrics

Metrics for a single Key.

Fields
name

string

Output only. Identifier. The name of the metrics, in the format projects/{project}/keys/{key}/metrics.

start_time

Timestamp

Inclusive start time aligned to a day (UTC).

score_metrics[]

ScoreMetrics

Metrics are continuous and in order by dates, and in the granularity of day. All Key types should have score-based data.

challenge_metrics[]

ChallengeMetrics

Metrics are continuous and in order by dates, and in the granularity of day. Only challenge-based keys (CHECKBOX, INVISIBLE) have challenge-based data.

MigrateKeyRequest

The migrate key request message.

Fields
name

string

Required. The name of the key to be migrated, in the format projects/{project}/keys/{key}.

skip_billing_check

bool

Optional. If true, skips the billing check. A reCAPTCHA Enterprise key or migrated key behaves differently than a reCAPTCHA (non-Enterprise version) key when you reach a quota limit (see https://cloud.google.com/recaptcha/quotas#quota_limit). To avoid any disruption of your usage, we check that a billing account is present. If your usage of reCAPTCHA is under the free quota, you can safely skip the billing check and proceed with the migration. See https://cloud.google.com/recaptcha/docs/billing-information.

PhoneFraudAssessment

Assessment for Phone Fraud

Fields
sms_toll_fraud_verdict

SmsTollFraudVerdict

Output only. Assessment of this phone event for risk of SMS toll fraud.

PrivatePasswordLeakVerification

Private password leak verification info.

Fields
lookup_hash_prefix

bytes

Required. Exactly 26-bit prefix of the SHA-256 hash of the canonicalized username. It is used to look up password leaks associated with that hash prefix.

encrypted_user_credentials_hash

bytes

Optional. Encrypted Scrypt hash of the canonicalized username+password. It is re-encrypted by the server and returned through reencrypted_user_credentials_hash.

encrypted_leak_match_prefixes[]

bytes

Output only. List of prefixes of the encrypted potential password leaks that matched the given parameters. They must be compared with the client-side decryption prefix of reencrypted_user_credentials_hash

reencrypted_user_credentials_hash

bytes

Output only. Corresponds to the re-encryption of the encrypted_user_credentials_hash field. It is used to match potential password leaks within encrypted_leak_match_prefixes.

RelatedAccountGroup

A group of related accounts.

Fields
name

string

Required. Identifier. The resource name for the related account group in the format projects/{project}/relatedaccountgroups/{related_account_group}.

RelatedAccountGroupMembership

A membership in a group of related accounts.

Fields
name

string

Required. Identifier. The resource name for this membership in the format projects/{project}/relatedaccountgroups/{relatedaccountgroup}/memberships/{membership}.

account_id

string

The unique stable account identifier of the member. The identifier corresponds to an account_id provided in a previous CreateAssessment or AnnotateAssessment call.

hashed_account_id
(deprecated)

bytes

Deprecated: use account_id instead. The unique stable hashed account identifier of the member. The identifier corresponds to a hashed_account_id provided in a previous CreateAssessment or AnnotateAssessment call.

RemoveIpOverrideRequest

The removeIpOverride request message.

Fields
name

string

Required. The name of the key from which the IP override is removed, in the format projects/{project}/keys/{key}.

ip_override_data

IpOverrideData

Required. IP override to be removed from the key.

RemoveIpOverrideResponse

This type has no fields.

Response for RemoveIpOverride.

ReorderFirewallPoliciesRequest

The reorder firewall policies request message.

Fields
parent

string

Required. The name of the project to list the policies for, in the format projects/{project}.

names[]

string

Required. A list containing all policy names, in the new order. Each name is in the format projects/{project}/firewallpolicies/{firewallpolicy}.

ReorderFirewallPoliciesResponse

This type has no fields.

The reorder firewall policies response message.

RetrieveLegacySecretKeyRequest

The retrieve legacy secret key request message.

Fields
key

string

Required. The public key name linked to the requested secret key in the format projects/{project}/keys/{key}.

RetrieveLegacySecretKeyResponse

Secret key is used only in legacy reCAPTCHA. It must be used in a 3rd party integration with legacy reCAPTCHA.

Fields
legacy_secret_key

string

The secret key (also known as shared secret) authorizes communication between your application backend and the reCAPTCHA Enterprise server to create an assessment. The secret key needs to be kept safe for security purposes.

RiskAnalysis

Risk analysis result for an event.

Fields
score

float

Output only. Legitimate event score from 0.0 to 1.0. (1.0 means very likely legitimate traffic while 0.0 means very likely non-legitimate traffic).

reasons[]

ClassificationReason

Output only. Reasons contributing to the risk analysis verdict.

extended_verdict_reasons[]

string

Output only. Extended verdict reasons to be used for experimentation only. The set of possible reasons is subject to change.

challenge

Challenge

Output only. Challenge information for SCORE_AND_CHALLENGE keys

Challenge

Challenge information for SCORE_AND_CHALLENGE keys

Enums
CHALLENGE_UNSPECIFIED Default unspecified type.
NOCAPTCHA No challenge was presented for solving.
PASSED A solution was submitted that was correct.
FAILED A solution was submitted that was incorrect or otherwise deemed suspicious.

ClassificationReason

Reasons contributing to the risk analysis verdict.

Enums
CLASSIFICATION_REASON_UNSPECIFIED Default unspecified type.
AUTOMATION Interactions matched the behavior of an automated agent.
UNEXPECTED_ENVIRONMENT The event originated from an illegitimate environment.
TOO_MUCH_TRAFFIC Traffic volume from the event source is higher than normal.
UNEXPECTED_USAGE_PATTERNS Interactions with the site were significantly different than expected patterns.
LOW_CONFIDENCE_SCORE Too little traffic has been received from this site thus far to generate quality risk analysis.
SUSPECTED_CARDING The request matches behavioral characteristics of a carding attack.
SUSPECTED_CHARGEBACK The request matches behavioral characteristics of chargebacks for fraud.

ScoreDistribution

Score distribution.

Fields
score_buckets

map<int32, int64>

Map key is score value multiplied by 100. The scores are discrete values between [0, 1]. The maximum number of buckets is on order of a few dozen, but typically much lower (ie. 10).

ScoreMetrics

Metrics related to scoring.

Fields
overall_metrics

ScoreDistribution

Aggregated score metrics for all traffic.

action_metrics

map<string, ScoreDistribution>

Action-based metrics. The map key is the action name which specified by the site owners at time of the "execute" client-side call.

SearchRelatedAccountGroupMembershipsRequest

The request message to search related account group memberships.

Fields
project

string

Required. The name of the project to search related account group memberships from. Specify the project name in the following format: projects/{project}.

account_id

string

Optional. The unique stable account identifier used to search connections. The identifier should correspond to an account_id provided in a previous CreateAssessment or AnnotateAssessment call. Either hashed_account_id or account_id must be set, but not both.

hashed_account_id
(deprecated)

bytes

Optional. Deprecated: use account_id instead. The unique stable hashed account identifier used to search connections. The identifier should correspond to a hashed_account_id provided in a previous CreateAssessment or AnnotateAssessment call. Either hashed_account_id or account_id must be set, but not both.

page_size

int32

Optional. The maximum number of groups to return. The service might return fewer than this value. If unspecified, at most 50 groups are returned. The maximum value is 1000; values above 1000 are coerced to 1000.

page_token

string

Optional. A page token, received from a previous SearchRelatedAccountGroupMemberships call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to SearchRelatedAccountGroupMemberships must match the call that provided the page token.

SearchRelatedAccountGroupMembershipsResponse

The response to a SearchRelatedAccountGroupMemberships call.

Fields
related_account_group_memberships[]

RelatedAccountGroupMembership

The queried memberships.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

SmsTollFraudVerdict

Information about SMS toll fraud.

Fields
risk

float

Output only. Probability of an SMS event being fraudulent. Values are from 0.0 (lowest) to 1.0 (highest).

reasons[]

SmsTollFraudReason

Output only. Reasons contributing to the SMS toll fraud verdict.

SmsTollFraudReason

Reasons contributing to the SMS toll fraud verdict.

Enums
SMS_TOLL_FRAUD_REASON_UNSPECIFIED Default unspecified reason
INVALID_PHONE_NUMBER The provided phone number was invalid

TestingOptions

Options for user acceptance testing.

Fields
testing_score

float

Optional. All assessments for this Key return this score. Must be between 0 (likely not legitimate) and 1 (likely legitimate) inclusive.

testing_challenge

TestingChallenge

Optional. For challenge-based keys only (CHECKBOX, INVISIBLE), all challenge requests for this site return nocaptcha if NOCAPTCHA, or an unsolvable challenge if CHALLENGE.

TestingChallenge

Enum that represents the challenge option for challenge-based (CHECKBOX, INVISIBLE) testing keys.

Enums
TESTING_CHALLENGE_UNSPECIFIED Perform the normal risk analysis and return either nocaptcha or a challenge depending on risk and trust factors.
NOCAPTCHA Challenge requests for this key always return a nocaptcha, which does not require a solution.
UNSOLVABLE_CHALLENGE Challenge requests for this key always return an unsolvable challenge.

TokenProperties

Properties of the provided event token.

Fields
valid

bool

Output only. Whether the provided user response token is valid. When valid = false, the reason could be specified in invalid_reason or it could also be due to a user failing to solve a challenge or a sitekey mismatch (i.e the sitekey used to generate the token was different than the one specified in the assessment).

invalid_reason

InvalidReason

Output only. Reason associated with the response when valid = false.

create_time

Timestamp

Output only. The timestamp corresponding to the generation of the token.

hostname

string

Output only. The hostname of the page on which the token was generated (Web keys only).

android_package_name

string

Output only. The name of the Android package with which the token was generated (Android keys only).

ios_bundle_id

string

Output only. The ID of the iOS bundle with which the token was generated (iOS keys only).

action

string

Output only. Action name provided at token generation.

InvalidReason

Enum that represents the types of invalid token reasons.

Enums
INVALID_REASON_UNSPECIFIED Default unspecified type.
UNKNOWN_INVALID_REASON If the failure reason was not accounted for.
MALFORMED The provided user verification token was malformed.
EXPIRED The user verification token had expired.
DUPE The user verification had already been seen.
MISSING The user verification token was not present.
BROWSER_ERROR A retriable error (such as network failure) occurred on the browser. Could easily be simulated by an attacker.

TransactionData

Transaction data associated with a payment protected by reCAPTCHA Enterprise.

Fields
payment_method

string

Optional. The payment method for the transaction. The allowed values are:

  • credit-card
  • debit-card
  • gift-card
  • processor-{name} (If a third-party is used, for example, processor-paypal)
  • custom-{name} (If an alternative method is used, for example, custom-crypto)
card_bin

string

Optional. The Bank Identification Number - generally the first 6 or 8 digits of the card.

card_last_four

string

Optional. The last four digits of the card.

currency_code

string

Optional. The currency code in ISO-4217 format.

value

double

Optional. The decimal value of the transaction in the specified currency.

shipping_value

double

Optional. The value of shipping in the specified currency. 0 for free or no shipping.

shipping_address

Address

Optional. Destination address if this transaction involves shipping a physical item.

billing_address

Address

Optional. Address associated with the payment method when applicable.

user

User

Optional. Information about the user paying/initiating the transaction.

merchants[]

User

Optional. Information about the user or users fulfilling the transaction.

items[]

Item

Optional. Items purchased in this transaction.

gateway_info

GatewayInfo

Optional. Information about the payment gateway's response to the transaction.

transaction_id

string

Unique identifier for the transaction. This custom identifier can be used to reference this transaction in the future, for example, labeling a refund or chargeback event. Two attempts at the same transaction should use the same transaction id.

Address

Structured address format for billing and shipping addresses.

Fields
recipient

string

Optional. The recipient name, potentially including information such as "care of".

address[]

string

Optional. The first lines of the address. The first line generally contains the street name and number, and further lines may include information such as an apartment number.

locality

string

Optional. The town/city of the address.

administrative_area

string

Optional. The state, province, or otherwise administrative area of the address.

region_code

string

Optional. The CLDR country/region of the address.

postal_code

string

Optional. The postal or ZIP code of the address.

GatewayInfo

Details about the transaction from the gateway.

Fields
name

string

Optional. Name of the gateway service (for example, stripe, square, paypal).

gateway_response_code

string

Optional. Gateway response code describing the state of the transaction.

avs_response_code

string

Optional. AVS response code from the gateway (available only when reCAPTCHA Enterprise is called after authorization).

cvv_response_code

string

Optional. CVV response code from the gateway (available only when reCAPTCHA Enterprise is called after authorization).

Item

Line items being purchased in this transaction.

Fields
name

string

Optional. The full name of the item.

value

double

Optional. The value per item that the user is paying, in the transaction currency, after discounts.

quantity

int64

Optional. The quantity of this item that is being purchased.

merchant_account_id

string

Optional. When a merchant is specified, its corresponding account_id. Necessary to populate marketplace-style transactions.

User

Details about a user's account involved in the transaction.

Fields
account_id

string

Optional. Unique account identifier for this user. If using account defender, this should match the hashed_account_id field. Otherwise, a unique and persistent identifier for this account.

creation_ms

int64

Optional. The epoch milliseconds of the user's account creation.

email

string

Optional. The email address of the user.

email_verified

bool

Optional. Whether the email has been verified to be accessible by the user (OTP or similar).

phone_number

string

Optional. The phone number of the user, with country code.

phone_verified

bool

Optional. Whether the phone number has been verified to be accessible by the user (OTP or similar).

TransactionEvent

Describes an event in the lifecycle of a payment transaction.

Fields
event_type

TransactionEventType

Optional. The type of this transaction event.

reason

string

Optional. The reason or standardized code that corresponds with this transaction event, if one exists. For example, a CHARGEBACK event with code 6005.

value

double

Optional. The value that corresponds with this transaction event, if one exists. For example, a refund event where $5.00 was refunded. Currency is obtained from the original transaction data.

event_time

Timestamp

Optional. Timestamp when this transaction event occurred; otherwise assumed to be the time of the API call.

TransactionEventType

Enum that represents an event in the payment transaction lifecycle.

Enums
TRANSACTION_EVENT_TYPE_UNSPECIFIED Default, unspecified event type.
MERCHANT_APPROVE Indicates that the transaction is approved by the merchant. The accompanying reasons can include terms such as 'INHOUSE', 'ACCERTIFY', 'CYBERSOURCE', or 'MANUAL_REVIEW'.
MERCHANT_DENY Indicates that the transaction is denied and concluded due to risks detected by the merchant. The accompanying reasons can include terms such as 'INHOUSE', 'ACCERTIFY', 'CYBERSOURCE', or 'MANUAL_REVIEW'.
MANUAL_REVIEW Indicates that the transaction is being evaluated by a human, due to suspicion or risk.
AUTHORIZATION Indicates that the authorization attempt with the card issuer succeeded.
AUTHORIZATION_DECLINE Indicates that the authorization attempt with the card issuer failed. The accompanying reasons can include Visa's '54' indicating that the card is expired, or '82' indicating that the CVV is incorrect.
PAYMENT_CAPTURE Indicates that the transaction is completed because the funds were settled.
PAYMENT_CAPTURE_DECLINE Indicates that the transaction could not be completed because the funds were not settled.
CANCEL Indicates that the transaction has been canceled. Specify the reason for the cancellation. For example, 'INSUFFICIENT_INVENTORY'.
CHARGEBACK_INQUIRY Indicates that the merchant has received a chargeback inquiry due to fraud for the transaction, requesting additional information before a fraud chargeback is officially issued and a formal chargeback notification is sent.
CHARGEBACK_ALERT Indicates that the merchant has received a chargeback alert due to fraud for the transaction. The process of resolving the dispute without involving the payment network is started.
FRAUD_NOTIFICATION Indicates that a fraud notification is issued for the transaction, sent by the payment instrument's issuing bank because the transaction appears to be fraudulent. We recommend including TC40 or SAFE data in the reason field for this event type. For partial chargebacks, we recommend that you include an amount in the value field.
CHARGEBACK Indicates that the merchant is informed by the payment network that the transaction has entered the chargeback process due to fraud. Reason code examples include Discover's '6005' and '6041'. For partial chargebacks, we recommend that you include an amount in the value field.
CHARGEBACK_REPRESENTMENT Indicates that the transaction has entered the chargeback process due to fraud, and that the merchant has chosen to enter representment. Reason examples include Discover's '6005' and '6041'. For partial chargebacks, we recommend that you include an amount in the value field.
CHARGEBACK_REVERSE Indicates that the transaction has had a fraud chargeback which was illegitimate and was reversed as a result. For partial chargebacks, we recommend that you include an amount in the value field.
REFUND_REQUEST Indicates that the merchant has received a refund for a completed transaction. For partial refunds, we recommend that you include an amount in the value field. Reason example: 'TAX_EXEMPT' (partial refund of exempt tax)
REFUND_DECLINE Indicates that the merchant has received a refund request for this transaction, but that they have declined it. For partial refunds, we recommend that you include an amount in the value field. Reason example: 'TAX_EXEMPT' (partial refund of exempt tax)
REFUND Indicates that the completed transaction was refunded by the merchant. For partial refunds, we recommend that you include an amount in the value field. Reason example: 'TAX_EXEMPT' (partial refund of exempt tax)
REFUND_REVERSE Indicates that the completed transaction was refunded by the merchant, and that this refund was reversed. For partial refunds, we recommend that you include an amount in the value field.

UpdateFirewallPolicyRequest

The update firewall policy request message.

Fields
firewall_policy

FirewallPolicy

Required. The policy to update.

update_mask

FieldMask

Optional. The mask to control which fields of the policy get updated. If the mask is not present, all fields are updated.

UpdateKeyRequest

The update key request message.

Fields
key

Key

Required. The key to update.

update_mask

FieldMask

Optional. The mask to control which fields of the key get updated. If the mask is not present, all fields are updated.

UserId

An identifier associated with a user.

Fields

Union field id_oneof.

id_oneof can be only one of the following:

email

string

Optional. An email address.

phone_number

string

Optional. A phone number. Should use the E.164 format.

username

string

Optional. A unique username, if different from all the other identifiers and account_id that are provided. Can be a unique login handle or display name for a user.

UserInfo

User information associated with a request protected by reCAPTCHA Enterprise.

Fields
create_account_time

Timestamp

Optional. Creation time for this account associated with this user. Leave blank for non logged-in actions, guest checkout, or when there is no account associated with the current user.

account_id

string

Optional. For logged-in requests or login/registration requests, the unique account identifier associated with this user. You can use the username if it is stable (meaning it is the same for every request associated with the same user), or any stable user ID of your choice. Leave blank for non logged-in actions or guest checkout.

user_ids[]

UserId

Optional. Identifiers associated with this user or request.

WafSettings

Settings specific to keys that can be used for WAF (Web Application Firewall).

Fields
waf_service

WafService

Required. The WAF service that uses this key.

waf_feature

WafFeature

Required. The WAF feature for which this key is enabled.

WafFeature

Supported WAF features. For more information, see https://cloud.google.com/recaptcha/docs/usecase#comparison_of_features.

Enums
WAF_FEATURE_UNSPECIFIED Undefined feature.
CHALLENGE_PAGE Redirects suspicious traffic to reCAPTCHA.
SESSION_TOKEN Use reCAPTCHA session-tokens to protect the whole user session on the site's domain.
ACTION_TOKEN Use reCAPTCHA action-tokens to protect user actions.
EXPRESS Use reCAPTCHA WAF express protection to protect any content other than web pages, like APIs and IoT devices.

WafService

Web Application Firewalls supported by reCAPTCHA.

Enums
WAF_SERVICE_UNSPECIFIED Undefined WAF
CA Cloud Armor
FASTLY Fastly
CLOUDFLARE Cloudflare
AKAMAI Akamai

WebKeySettings

Settings specific to keys that can be used by websites.

Fields
allow_all_domains

bool

Optional. If set to true, it means allowed_domains are not enforced.

allowed_domains[]

string

Optional. Domains or subdomains of websites allowed to use the key. All subdomains of an allowed domain are automatically allowed. A valid domain requires a host and must not include any path, port, query or fragment. Examples: 'example.com' or 'subdomain.example.com'

allow_amp_traffic

bool

Optional. If set to true, the key can be used on AMP (Accelerated Mobile Pages) websites. This is supported only for the SCORE integration type.

integration_type

IntegrationType

Required. Describes how this key is integrated with the website.

challenge_security_preference

ChallengeSecurityPreference

Optional. Settings for the frequency and difficulty at which this key triggers captcha challenges. This should only be specified for IntegrationTypes CHECKBOX and INVISIBLE and SCORE_AND_CHALLENGE.

ChallengeSecurityPreference

Enum that represents the possible challenge frequency and difficulty configurations for a web key.

Enums
CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED Default type that indicates this enum hasn't been specified.
USABILITY Key tends to show fewer and easier challenges.
BALANCE Key tends to show balanced (in amount and difficulty) challenges.
SECURITY Key tends to show more and harder challenges.

IntegrationType

Enum that represents the integration types for web keys.

Enums
INTEGRATION_TYPE_UNSPECIFIED Default type that indicates this enum hasn't been specified. This is not a valid IntegrationType, one of the other types must be specified instead.
SCORE Only used to produce scores. It doesn't display the "I'm not a robot" checkbox and never shows captcha challenges.
CHECKBOX Displays the "I'm not a robot" checkbox and may show captcha challenges after it is checked.
INVISIBLE Doesn't display the "I'm not a robot" checkbox, but may show captcha challenges after risk analysis.