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. URI path of the API endpoint to protect. Must start with '/'. Supports glob characters '*' to match a single path segment and '**' to match multiple path segments. Standalone root catch-alls ('/*' and '/**') are invalid because it would hurt performance to trigger reCAPTCHA on every single request to your backend.

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 is not case-sensitive and 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,

  // Union field outcome can be only one of the following:
  "noChallenge": {
    object (NoChallengeOutcome)
  },
  "challenge": {
    object (ChallengeOutcome)
  }
  // End of list of possible types for union field outcome.
}
Fields
condition

string

Optional. A CEL condition that must be met for this rule to apply. 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"
Union field outcome. Required. The outcome to apply when this challenge rule matches. outcome can be only one of the following:
noChallenge

object (NoChallengeOutcome)

Do not present a challenge to the user.
challenge

object (ChallengeOutcome)

Present a challenge to the user.

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.