REST Resource: projects.keys

Resource: Key

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

JSON representation 
{
  "name": string,
  "displayName": string,
  "labels": {
    string: string,
    ...
  },
  "createTime": string,
  "testingOptions": {
    object (TestingOptions)
  },
  "wafSettings": {
    object (WafSettings)
  },

  // Union field platform_settings can be only one of the following:
  "webSettings": {
    object (WebKeySettings)
  },
  "androidSettings": {
    object (AndroidKeySettings)
  },
  "iosSettings": {
    object (IOSKeySettings)
  },
  "expressSettings": {
    object (ExpressKeySettings)
  },
  "universalSettings": {
    object (UniversalKeySettings)
  }
  // End of list of possible types for union field platform_settings.
}
Fields
name

string

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

string

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

map (key: string, value: string)

Optional. See Creating and managing labels.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
createTime

string (Timestamp format)

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

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
testingOptions

object (TestingOptions)

Optional. Options for user acceptance testing.
wafSettings

object (WafSettings)

Optional. Settings for Web Application Firewall (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:
webSettings

object (WebKeySettings)

Settings for keys that can be used by websites.
androidSettings

object (AndroidKeySettings)

Settings for keys that can be used by Android apps.
iosSettings

object (IOSKeySettings)

Settings for keys that can be used by iOS apps.
expressSettings

object (ExpressKeySettings)

Settings for keys that can be used by reCAPTCHA Express.
universalSettings

object (UniversalKeySettings)

Settings for keys that are configured through their Policy.

WebKeySettings

Settings specific to keys that can be used by websites.

JSON representation 
{
  "allowAllDomains": boolean,
  "allowedDomains": [
    string
  ],
  "allowAmpTraffic": boolean,
  "integrationType": enum (IntegrationType),
  "challengeSecurityPreference": enum (ChallengeSecurityPreference),
  "challengeSettings": {
    object (ChallengeSettings)
  }
}
Fields
allowAllDomains

boolean

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

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' Each key supports a maximum of 250 domains. To use a key 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.
allowAmpTraffic

boolean

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.
integrationType

enum (IntegrationType)

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

enum (ChallengeSecurityPreference)

Optional. Settings for the frequency and difficulty at which this key triggers captcha challenges. This should only be specified for IntegrationType CHECKBOX, INVISIBLE or POLICY_BASED_CHALLENGE.
challengeSettings

object (ChallengeSettings)

Optional. Challenge settings.

IntegrationType

Enum that represents the integration types for web keys. Ensure that applications can handle values not explicitly listed.

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.
POLICY_BASED_CHALLENGE Displays a visual challenge or not depending on the user risk analysis score.

ChallengeSecurityPreference

Enum that represents the possible challenge frequency and difficulty configurations for a web key. Ensure that applications can handle values not explicitly listed.

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.

ChallengeSettings

Settings for POLICY_BASED_CHALLENGE keys to control when a challenge is triggered.

JSON representation 
{
  "defaultSettings": {
    object (ActionSettings)
  },
  "actionSettings": {
    string: {
      object (ActionSettings)
    },
    ...
  }
}
Fields
defaultSettings

object (ActionSettings)

Required. Defines when a challenge is triggered (unless the default threshold is overridden for the given action, see actionSettings).
actionSettings

map (key: string, value: object (ActionSettings))

Optional. The action to score threshold map. The action name should be the same as the action name passed in the data-action attribute (see https://cloud.google.com/recaptcha/docs/actions-website). Action names are case-insensitive. There is a maximum of 100 action settings. An action name has a maximum length of 100.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

ActionSettings

Per-action challenge settings.

JSON representation 
{
  "scoreThreshold": number
}
Fields
scoreThreshold

number

Required. A challenge is triggered if the end-user score is below that threshold. Value must be between 0 and 1 (inclusive).

AndroidKeySettings

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

JSON representation 
{
  "allowAllPackageNames": boolean,
  "allowedPackageNames": [
    string
  ],
  "supportNonGoogleAppStoreDistribution": boolean
}
Fields
allowAllPackageNames

boolean

Optional. If set to true, allowedPackageNames are not enforced.
allowedPackageNames[]

string

Optional. Android package names of apps allowed to use the key. Example: 'com.companyname.appname' Each key supports a maximum of 250 package names. To use a key on more apps, set allowAllPackageNames to true. When this is set, you are responsible for validating the package name by checking the tokenProperties.android_package_name field in each assessment response against your list of allowed package names.
supportNonGoogleAppStoreDistribution

boolean

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.

IOSKeySettings

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

JSON representation 
{
  "allowAllBundleIds": boolean,
  "allowedBundleIds": [
    string
  ],
  "appleDeveloperId": {
    object (AppleDeveloperId)
  }
}
Fields
allowAllBundleIds

boolean

Optional. If set to true, allowedBundleIds are not enforced.
allowedBundleIds[]

string

Optional. iOS bundle IDs of apps allowed to use the key. Example: 'com.companyname.productname.appname' Each key supports a maximum of 250 bundle IDs. To use a key on more apps, set allowAllBundleIds to true. When this is set, you are responsible for validating the bundle id by checking the tokenProperties.ios_bundle_id field in each assessment response against your list of allowed bundle IDs.
appleDeveloperId

object (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.

AppleDeveloperId

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

JSON representation 
{
  "privateKey": string,
  "keyId": string,
  "teamId": string
}
Fields
privateKey

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.
keyId

string

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

string

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

ExpressKeySettings

This type has no fields.

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

UniversalKeySettings

This type has no fields.

Settings for keys that are configured through their Policy.

TestingOptions

Options for user acceptance testing.

JSON representation 
{
  "testingScore": number,
  "testingChallenge": enum (TestingChallenge)
}
Fields
testingScore

number

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

enum (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 (for example, CHECKBOX and INVISIBLE) testing keys. Ensure that applications can handle values not explicitly listed.

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.

WafSettings

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

JSON representation 
{
  "wafService": enum (WafService),
  "wafFeature": enum (WafFeature)
}
Fields
wafService

enum (WafService)

Required. The Web Application Firewall (WAF) service that uses this key.
wafFeature

enum (WafFeature)

Required. The Web Application Firewall (WAF) feature for which this key is enabled.

WafService

Web Application Firewalls that reCAPTCHA supports. Ensure that applications can handle values not explicitly listed.

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

WafFeature

Supported WAF features. For more information, see https://cloud.google.com/recaptcha/docs/usecase#comparison_of_features. Ensure that applications can handle values not explicitly listed.

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

Deprecated: Use expressSettings instead.

Methods

addIpOverride

 Adds an IP override to a key.

create

 Creates a new reCAPTCHA Enterprise key.

delete

 Deletes the specified key.

get

 Returns the specified key.

getMetrics

 Get some aggregated metrics for a Key.

getPolicy

 Get the policy for a key.

list

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

listIpOverrides

 Lists all IP overrides for a key.

migrate

 Migrates an existing key from reCAPTCHA to reCAPTCHA Enterprise.

patch

 Updates the specified key.

removeIpOverride

 Removes an IP override from a key.

retrieveLegacySecretKey

 Returns the secret key related to the specified public key.

updatePolicy

 Updates the policy for a key.