PingOne Platform APIs

Forms Recaptcha

The Recaptcha configuration API provides support for a Recaptcha V2 field in a form definition. It includes operations to read, update, and delete the environment’s Recaptcha configuration.

Before you can define your environment’s Recaptcha configuration in PingOne, you must register your site domain with Google to create a Recaptcha configuration. For more information about how to create the Google configuration for your domain, refer to Google reCAPTCHA. After you complete the configuration, Google provides the secret key and site key that you need to set your environment’s PingOne Recaptcha configuration.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Recaptcha V2 data model

Property Description

created

The time the configuration was created.

environment.id

A string that specifies the environment’s unique identifier.

modified

The time the configuration was last updated.

siteKey

A string that specifies the public site key for the Recaptcha configuration provided by Google. This is a required property.

secretKey

A string that specifies the confidential secret key for the Recaptcha configuration provided by Google. This is a required property.

Response codes

Code Message

200

Successful operation.

204

No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

Recaptcha V2 configuration errors

In addition to the general error codes, reCAPTCHA V2 configuration operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or OUT_OF_RANGE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [siteKey must not be blank] or Validation Error : [siteKey size must be between 1 and 100])

When and details

When: A PUT /recaptchaV2Config request omits the required siteKey or secretKey property, supplies an empty value for either, or supplies a value longer than 100 characters

Details: Detail EMPTY_VALUE for an omitted or blank value, or OUT_OF_RANGE with rangeMinimumValue and rangeMaximumValue inner errors for a value longer than 100 characters, target = the field path, message = the constraint message.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: The request body cannot be deserialized

Details: For a JSON field conversion error, the detail is Invalid value for attribute. and the target is the field path. Otherwise no detail is returned.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the formBuilder:read:recaptchaV2Config permission (GET), the formBuilder:update:recaptchaV2Config permission (PUT), or the formBuilder:delete:recaptchaV2Config permission (DELETE)

Details: None.