Policy

A complete configuration set containing multiple grouped rules defining the behavior of reCAPTCHA for fraud detection and prevention.

JSON representation 
{
  "name": string,
  "clientSettings": {
    object (ClientSettings)
  },
  "challengeRuleGroups": [
    {
      object (ChallengeRuleGroup)
    }
  ]
}
Fields
name

string

Identifier. Resource name for this policy. Format: "projects/{project}/keys/{key}/policy" for a policy under a key.
clientSettings

object (ClientSettings)

Required. Configuration for clients protected by this policy.
challengeRuleGroups[]

object (ChallengeRuleGroup)

Optional. Rules to configure the behavior of reCAPTCHA for showing a challenge. Rule groups are evaluated in order. Evaluation stops when the first matching rule group is found.

ClientSettings

Configuration for clients to protect with reCAPTCHA.

JSON representation 
{
  "allowedDomains": [
    string
  ],
  "allowAllDomains": boolean,
  "protectedEndpointGroup": {
    object (ProtectedEndpointGroup)
  }
}
Fields
allowedDomains[]

string

Optional. Domains or subdomains of websites allowed to use the policy. 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' Each policy supports a maximum of 250 domains. To use a policy on more domains, set allowAllDomains to true. When this is set, you are responsible for validating the hostname by checking the tokenProperties.hostname field in each assessment response against your list of allowed domains.
allowAllDomains

boolean

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

object (ProtectedEndpointGroup)

Optional. Configuration for all API endpoints to protect with reCAPTCHA. If this field is not set, reCAPTCHA will not automatically request tokens on any API endpoints.

ProtectedEndpointGroup

Configuration for API endpoints to protect with reCAPTCHA.

JSON representation 
{
  "protectedEndpoints": [
    {
      object (ProtectedEndpoint)
    }
  ]
}
Fields
protectedEndpoints[]

object (ProtectedEndpoint)

Optional. List of API endpoints to automatically protect with reCAPTCHA. If any of these endpoints is invoked from a page where a key bound to this policy is installed, a reCAPTCHA token is automatically generated and attached to the request. If multiple protected endpoints match a given API endpoint, the first one in the list is used.

ProtectedEndpoint

Configuration for an API endpoint to protect with reCAPTCHA.

JSON representation 
{
  "path": string,
  "action": string
}
Fields
path

string

Required. The URI path of the API endpoint to protect. The path is case-sensitive and must meet the following criteria:

  • Be unique, start with /, and contain 1 to 200 characters without consecutive slashes (//).
  • Include at least one non-wildcard segment. For example, cannot be /, /*, /**, or /*/.
  • Wildcards must occupy complete segments: * matches a single segment. For example, /api/*/login or /api/* are valid; /api/login* is invalid, and ** matches multiple segments as the final segment only. For example, /api/** is valid; /api/**/login is invalid.

Matching is evaluated against the URL path only. Domain, scheme, and query parameters are ignored.

Examples:

  • /login matches /login, https://example.com/login, and /login?query=1, but not /login/step1.
  • /products/* matches /products/123, but not /products/123/456.
  • /content/** matches /content/articles/2024/01/01.
action

string

Required. Action name to be used for token generation for this endpoint. The action name can only contain alphanumeric characters, slashes, and underscores.

ChallengeRuleGroup

A collection of challenge rules that applies to one or more actions.

JSON representation 
{
  "actions": [
    string
  ],
  "challengeRules": [
    {
      object (ChallengeRule)
    }
  ]
}
Fields
actions[]

string

Required. Action name provided at token generation. The action name is not case-sensitive and can only contain alphanumeric characters, slashes, and underscores. If "*" is provided, the rule group applies to all actions. If multiple actions are provided, the rule group is applied to all of them. This field is required.
challengeRules[]

object (ChallengeRule)

Required. A list of rules that configure when and how reCAPTCHA presents a challenge. reCAPTCHA evaluates these rules in order and applies the first one that matches.

ChallengeRule

A rule to configure the behavior of reCAPTCHA for conditionally presenting a challenge.

JSON representation 
{
  "condition": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "noChallenge": {
    object (NoChallengeOutcome)
  },
  "challenge": {
    object (ChallengeOutcome)
  }
  // End of mutually exclusive fields.
}
Fields
condition

string

Optional. A CEL condition that must be met for this rule to apply. If unspecified, the rule applies unconditionally. The following fields can be referenced in the condition: * score * userIpAddress * user_asn * userAgent * verifiedBots.name * verifiedBots.bot_type

Examples: * score < 0.5 * userIpAddress == "123.45.67.89" * userAgent.contains("Chrome") * score < 0.5 && userIpAddress == "123.45.67.89"
Required. The outcome to apply when this challenge rule matches. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
noChallenge

object (NoChallengeOutcome)

Do not present a challenge to the user.
challenge

object (ChallengeOutcome)

Present a challenge to the user.
End of mutually exclusive fields.

NoChallengeOutcome

This type has no fields.

An outcome that indicates that no challenge should be presented to the user.

ChallengeOutcome

An outcome that indicates that a challenge of a specified difficulty should be presented to the user.

JSON representation 
{
  "difficulty": enum (ChallengeSecurityPreference)
}
Fields
difficulty

enum (ChallengeSecurityPreference)

Optional. The difficulty of the challenge to present to the user. If unspecified, BALANCE is used.