PingOne Platform APIs

Protect Settings

Use the riskSettings endpoint to specify maximum data retention periods for the risk data that is used by specific predictors.

You can define different data retention periods for each of the following risk predictors:

  • New Device

  • User Location Anomaly

  • User Base Risk Behavior

When you modify the maximum data retention period, the new period applies only to the new data that is collected after you changed the setting.

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.

Protect settings data model

Property Type Required Mutable Description

dataRetention

Object

Required

Mutable

The object that contains the fields for setting the data retention period for specific risk predictors.

dataRetention.newDeviceInDays

Integer

Optional

Mutable

The number of days that data for the New Device predictor should be retained. Minimum is 1, maximum is 180. Default is 180.

dataRetention.userBasedRiskBehaviorInDays

Integer

Optional

Mutable

The number of days that data for the User Based Risk Behavior predictor should be retained. Minimum is 30, maximum is 180. Default is 180.

dataRetention.userLocationAnomalyInDays

Integer

Optional

Mutable

The number of days that data for the User Location Anomaly predictor should be retained. Minimum is 30, maximum is 90. Default is 90.

environment.id

String

N/A

Read-only

The ID of the PingOne environment for which the Protect settings are being modified.

updatedAt

Date

N/A

Read-only

The date and time the Protect settings were last updated.

Protect settings errors

In addition to the general error codes, Protect settings 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 INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A PUT /environments/{envID}/riskSettings request omits the required dataRetention object, or supplies a dataRetention.newDeviceInDays value outside its allowed range (1 to 180, or 1 to 90 for environments created after the retention cutoff), a dataRetention.userLocationAnomalyInDays value outside 30 to 90, or a dataRetention.userBasedRiskBehaviorInDays value outside 30 to 180

Details: must not be null for an omitted dataRetention; must be greater than or equal to 1 or must be less than or equal to 90 for an out-of-range dataRetention.newDeviceInDays (or must be less than or equal to 180 for environments created before the retention cutoff); must be less than or equal to 90 (or must be greater than or equal to 30) for an out-of-range dataRetention.userLocationAnomalyInDays; must be greater than or equal to 30 or must be less than or equal to 180 for an out-of-range dataRetention.userBasedRiskBehaviorInDays; all with the failing property as the target, for example Validation Error : [dataRetention.userLocationAnomalyInDays must be less than or equal to 90].

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, for example a property with the wrong JSON type

Details: For a JSON field conversion error, the detail code is INVALID_VALUE with the failing field’s path as the target and message Invalid value for attribute.; otherwise no details are returned.

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the risk:read:riskSettings permission (read Protect settings) or the risk:update:riskSettings permission (update Protect settings)

Details: None

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request exceeded your license limit.

When and details

When: The environment does not have the advanced-predictors capability required to read or modify Protect settings

Details: Detail code LICENSE_EXCEEDED with message Action requires additional capabilities that are not included in your current license. and a missingCapabilities inner error.