PingOne Platform APIs

Device Authentication Policies

Device authentication policies (identified in the PingOne UI as "MFA Policies") enable you to configure different settings per MFA authentication method, according to your security policies.

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.

Device authentication policy data model

Property Type Required Mutable Description

authentication.deviceSelection

String

Optional

Mutable

The default method that should be used for authentication. Can take one of the following values:

* DEFAULT_TO_FIRST - use the method that the user set as their default

* PROMPT_TO_SELECT - always have the user select the method to use if there is more than one method available

* ALWAYS_DISPLAY_DEVICES - always have the user select the method to use even if there is only one method available

If this parameter is not provided, the DEFAULT_TO_FIRST option is used.

blockDisabledUsers

Boolean

Optional

Mutable

Set blockDisabledUsers to true if you want to add an additional security measure by ensuring that users whose accounts have been disabled cannot authenticate with MFA.

blockUsersWithDisabledMfa

Boolean

Optional

Mutable

By default, if a user’s MFA setting has been set to disabled, they are not able to authenticate. Set blockUsersWithDisabledMfa to false if you want to allow users to bypass MFA if their MFA setting has been disabled.

default

Boolean

Required

Mutable

Whether this is the default policy for Flow Manager.

email

Object

Required

Mutable

Email device authentication policy settings. Fields are detailed in Offline device (SMS, voice, email, WhatsApp) authentication policy data model.

environment

String

N/A

Read-only

The environment ID.

fido2

Object

Required

Mutable

FIDO device authentication policy settings. FIDO device authentication policy data model

forSignOnPolicy

Boolean

N/A

Read-only

Deprecated. Can still appear in responses.

id

String

N/A

Read-only

The ID of the device authentication policy.

ignoreUserLock

Boolean

Optional

Mutable

When applying an MFA policy, PingOne ordinarily checks if a user account is locked, and if so, prevents the user from authenticating. Set ignoreUserLock to true if you want PingOne to skip this account lock check.

mobile

Object

Required

Mutable

Mobile device authentication policy settings. Mobile authentication policy data model

name

String

Required

Immutable

The device authentication policy’s name.

newDeviceNotification

String

Optional

Mutable

Use newDeviceNotification to control whether a user should be notified if a new authentication method has been added to their account. Can take one of the following values:

* NONE - don’t notify the user when a new authentication method is added.

* EMAIL_THEN_SMS - notify the user by email. If there is no email address in the user profile, notify the user by SMS. If there is no phone number either, don’t notify the user.

* SMS_THEN_EMAIL - notify the user by SMS. If there is no phone number in the user profile, notify the user by email. If there is no email address either, don’t notify the user.

If the parameter is not provided, the default value is EMAIL_THEN_SMS.

notificationsPolicy.id

String

Optional

Mutable

If you want the MFA policy to use a specific notification policy rather than just using the default notification policy, use notificationsPolicy.id to specify the ID of the notification policy that should be used.

rememberMe

Object

Optional

Mutable

Object used to specify that the MFA policy should include a "remember me" option so that users do not have to authenticate when accessing applications from a device they have used already.

rememberMe.web

Object

Optional

Mutable

Contains the "remember me" settings for accessing applications from a browser.

rememberMe.web.enabled

Boolean

Optional

Mutable

Set to true if you want the MFA policy to include a "remember me" option.

rememberMe.web.lifeTime

Object

Optional

Mutable

Used to define the period during which users will not have to authenticate if they are accessing applications from a device they have used before. The "remember me" period can be anywhere from 1 hour to 90 days.

rememberMe.web.lifeTime.timeUnit

String

Optional

Mutable

The time unit to use for the "remember me" period. Can be HOURS or DAYS.

rememberMe.web.lifeTime.duration

Integer

Optional

Mutable

Used in conjunction with lifeTime.timeUnit to define the "remember me" period.

sms

Object

Required

Mutable

SMS device authentication policy settings. Fields are detailed in Offline device (SMS, voice, email, WhatsApp) authentication policy data model.

totp

Object

Required

Mutable

TOTP device authentication policy settings. TOTP authentication policy data model

updatedAt

Date

N/A

Read-only

When the resource was last updated.

voice

Object

Required

Mutable

Voice device authentication policy settings. Fields are detailed in Offline device (SMS, voice, email, WhatsApp) authentication policy data model.

whatsApp

Object

Optional

Mutable

Contains the settings for using WhatsApp as an authentication method. Fields are detailed in Offline device (SMS, voice, email, WhatsApp) authentication policy data model.

FIDO device authentication policy data model

All of the fields in the table below should be enclosed in the fido2 object, for example:

"fido2" : {
    "enabled" : true,
    "pairingDisabled" : false
}
Property Type Required Mutable Description

enabled

Boolean

Required

Mutable

Whether the authentication method is enabled or disabled in the policy.

failure

Object

Optional

Mutable

Contains the definitions for the maximum number of times authentication can fail before user is blocked temporarily, and how long the user should be blocked.

failure.coolDown.duration

Integer

Optional

Mutable

Used in conjunction with failure.coolDown.timeUnit to specify how long the user should be blocked after reaching the maximum number of failures, before they can try authenticating again. Minimum period is two minutes, maximum is 30 minutes.

failure.coolDown.timeUnit

String

Optional

Mutable

The units to use for failure.coolDown.duration. Can be SECONDS or MINUTES.

failure.count

Integer

Optional

Mutable

The maximum number of times that authentication can fail before user is blocked for the specified period. Minimum is 1, maximum is 7.

fido2PolicyId

String

Optional

Mutable

The ID of the specific FIDO policy that should be used. If this parameter is not provided, the default FIDO policy is used.

pairingDisabled

Boolean

Optional

Mutable

You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

Offline device (SMS, voice, email, WhatsApp) authentication policy data model

Property Type Required Mutable Description

enabled

Boolean

Required

Mutable

Whether the device is enabled or disabled in the policy.

otp.failure.coolDown.duration

Integer

Required

Mutable

The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 0, maximum is 30, and the default is 0. Note that when using the "onetime authentication" feature, the user is not blocked after the maximum number of failures even if you specified a block duration.

otp.failure.coolDown.timeUnit

String

Required

Mutable

The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.

otp.failure.count

Integer

Required

Mutable

The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.

otp.lifetime.duration

Integer

Required

Mutable

The duration (number of time units) that the passcode is valid before it expires. The minimum value is 1, maximum is 7, and the default is 3.

otp.lifetime.timeUnit

String

Required

Mutable

The type of time unit for otp.lifetime.duration. Valid values are MINUTES and SECONDS.

otp.otpLength

Integer

Optional

Mutable

Used to specify the length of the OTP that is shown to users. Minimum length is 6 digits and maximum is 10 digits. If the parameter is not provided, the default is 6 digits.

pairingDisabled

Boolean

Optional

Mutable

You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

Mobile device authentication policy data model

All of the fields in the table below should be enclosed in the mobile object, for example:

"mobile": {
    "enabled": true,
    "otp": {
        "failure": {
            "count": 3,
            "coolDown": {
                "duration": 2,
                "timeUnit": "MINUTES"
            }
        }
    },
    "applications": [
        {
            "id": "{{appID}}",
            "push": {
                "enabled": true,
                "numberMatching": {
                    "enabled": true
                }
            },
            "otp": {
                "enabled": true
            },
            "pushTimeout": {
                "duration" : 120,
                "timeUnit" : "SECONDS"
            },
            "pushLimit": {
                "count": 4,
                "timePeriod": {
                    "duration": 10,
                    "timeUnit": "MINUTES"
                },
                "lockDuration": {
                    "duration": 30,
                    "timeUnit": "MINUTES"
                }
            },
            "deviceAuthorization": {
                "enabled": true,
                "extraVerification": "permissive"
            },
            "autoEnrollment": {
                "enabled": true
            },
            "pairingKeyLifetime": {
                "duration": 40,
                "timeUnit": "HOURS"
            },
            "integrityDetection": "permissive"
        }
    ]
}
Property Type Required Mutable Description

applications[].autoEnrollment.enabled

Boolean

Required

Mutable

Set to true if you want the application to allow Auto Enrollment. Auto Enrollment means that the user can authenticate for the first time from an unpaired device, and the successful authentication will result in the pairing of the device for MFA.

applications[].deviceAuthorization.enabled

Boolean

Required

Mutable

Specifies the enabled or disabled state of automatic MFA for native devices paired with the user, for the specified application.

applications[].deviceAuthorization.extraVerification

String

Required

Mutable

Specifies the level of further verification when deviceAuthorization is enabled. The PingOne platform performs an extra verification check by sending a "silent" push notification to the customer native application, and receives a confirmation in return.
extraVerification can be one of the following levels:

* disabled (default): The PingOne platform does not perform the extra verification check.

* permissive: The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the native app, the MFA step is treated as successfully completed.

* restrictive: The PingOne platform performs the extra verification check.The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the native app, the MFA step is treated as failed.

</li></ul>

applications[].id

String

Required

Immutable

The application’s UUID.

applications[].integrityDetection

String

Required

Mutable

Controls how authentication or registration attempts should proceed if a device integrity check does not receive a response. Set the value to permissive if you want to allow the process to continue. Set the value to restrictive if you want to block the user in such situations.

applications[].otp.enabled

Boolean

Required

Mutable

Specifies whether OTP authentication is enabled or disabled for the policy.

applications[].pairingDisabled

Boolean

Optional

Mutable

You can set pairingDisabled to true to prevent users from pairing new devices with the relevant application. You can use this option if you want to phase out an existing mobile application but want to allow users to continue using the application for authentication for existing devices.

applications[].pairingKeyLifetime.duration

Integer

Optional

Mutable

The amount of time an issued pairing key can be used until it expires. Minimum is 1 minute and maximum is 48 hours. If this parameter is not provided, the duration is set to 10 minutes.

applications[].pairingKeyLifetime.timeUnit

String

Optional

Mutable

The time unit for the pairingKeyLifetime.duration parameter. The possible values are MINUTES and HOURS.

applications[].push.enabled

Boolean

Required

Mutable

Specifies whether push notification is enabled or disabled for the policy.

applications[].push.numberMatching.enabled

Boolean

Optional

Mutable

Set to true if you want the mobile push to require the user to match a number that they were shown when requesting access. To specify how the matching should be carried out, refer to the numberMatching.type parameter in the Applications OIDC settings data model.

applications[].pushLimit.count

Integer

Optional

Mutable

The number of consecutive push notifications that can be ignored or rejected by a user within a defined period before push notifications are blocked for the application. The minimum value is 1 and the maximum value is 50. If this parameter is not provided, the default value is 5.

applications[].pushLimit.lockDuration.duration

Integer

Optional

Mutable

The length of time that push notifications should be blocked for the application if the defined limit has been reached. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 30 minutes.

applications[].pushLimit.lockDuration.timeUnit

String

Optional

Mutable

The time unit for the pushLimit.lockDuration.duration parameter. The valid values are MINUTES and SECONDS.

applications[].pushLimit.timePeriod.duration

Integer

Optional

Mutable

The time period in which the push notifications are counted towards the defined limit. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 10 minutes.

applications[].pushLimit.timePeriod.timeUnit

String

Optional

Mutable

The time unit for the pushLimit.timePeriod.duration parameter. The valid values are MINUTES and SECONDS.

applications[].pushTimeout.duration

Integer

Optional

Mutable

The amount of time a user has to respond to a push notification before it expires. Minimum is 40 seconds and maximum is 150 seconds. If this parameter is not provided, the duration is set to 40 seconds.

applications[].pushTimeout.timeUnit

String

Optional

Mutable

The time unit for the pushTimeout.duration parameter. Currently, the only permitted value is SECONDS.

enabled

Boolean

Required

Mutable

Whether the device is enabled or disabled in the policy.

otp.failure.coolDown.duration

Integer

Required

Mutable

The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 2, maximum is 30, and the default is 2. Note that when using the "onetime authentication" feature, the user is not blocked after the maximum number of failures even if you specified a block duration.

otp.failure.coolDown.timeUnit

String

Required

Mutable

The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.

otp.failure.count

Integer

Required

Mutable

The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

TOTP device authentication policy data model

Property Type Required Mutable Description

enabled

Boolean

Required

Mutable

Whether the device is enabled or disabled in the policy.

otp.failure.coolDown.duration

Integer

Required

Mutable

The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 2, maximum is 30, and the default is 2.

otp.failure.coolDown.timeUnit

String

Required

Mutable

The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.

otp.failure.count

Integer

Required

Mutable

The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.

pairingDisabled

Boolean

Optional

Mutable

You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

passcodeGracePeriod

Integer

Optional

Mutable

Authenticator App (TOTP) passcodes are valid for 30 seconds (refresh duration). However, to cover time synchronization issues, there is a default grace period of 5 times the refresh duration in each direction. Taking the grace period into account, the passcode is valid for the base 30 seconds plus 5 x 30 = 150 seconds behind the time of issue and 150 seconds past the expiration time. You can use the passcodeGracePeriod parameter to shorten or lengthen this period. Specify the number of windows you want to use, with each window representing 30 seconds in both directions. Minimum value is 1 window (total of 90 seconds) and maximum value is 10 windows (total of 630 seconds).

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

uriParameters

Object

Optional

Mutable

Object that you can use to provide key:value pairs for otpauth URI parameters. For example, if you provide a value for the issuer parameter, then authenticators that support that parameter will display the text you specify together with the OTP (in addition to the username). This can help users recognize which application the OTP is for. If you intend on using the same MFA policy for multiple applications, choose a name that reflects the group of applications.

PingID method data model (for PingOne environments where PingID accounts have been integrated)

These fields are used for the PingID-specific authentication methods - desktop, Yubikey, and OATH token.

Property Type Required Mutable Description

enabled

Boolean

Required

Mutable

Whether the device is enabled or disabled in the policy.

otp.failure.coolDown.duration

Integer

Required

Mutable

The amount of time the user is blocked after reaching the maximum number of passcode failures. The minimum is one second and the maximum is 30 minutes. Note that when using the "onetime authentication" feature, the user is not blocked after the maximum number of failures even if you specified a block duration.

otp.failure.coolDown.timeUnit

String

Required

Mutable

The time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.

otp.failure.count

Integer

Required

Mutable

The maximum number of times that OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7.

pairingDisabled

Boolean

Optional

Mutable

You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

pairingKeyLifetime.duration

integer

Optional

Mutable

For "desktop" only. The amount of time the pairing key is valid. Can be expressed in minutes or hours. Minimum is one minute, maximum is 48 hours. If the pairingKeyLifetime object is not provided, then 48 hours is used.

pairingKeyLifetime.timeUnit

String

Optional

Mutable

The time unit for pairingKeyLifetime.duration. Can be MINUTES or HOURS.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

PingID app data model (for PingOne environments where PingID accounts have been integrated)

This table includes the properties that are used for the PingID mobile app. All of the fields in the table below should be enclosed in the mobile object, as in the example in Mobile device authentication policy data model.

Property Type Required Mutable Description

applications[].autoEnrollment.enabled

Boolean

N/A

Read-only

Not relevant for PingOne environments where PingID accounts have been integrated. Will always be returned as false.

applications[].biometricsEnabled

Boolean

Optional

Mutable

Set to true if you want to allow users to authenticate with the biometric methods supported by the PingID app.

applications[].id

String

Required

Immutable

The application’s UUID.

applications[].otp.enabled

Boolean

Optional

Mutable

Specifies whether the user can authenticate with a one-time passcode generated by the PingID app when push notifications are not available. If the parameter is not included, the option is disabled.

applications[].pairingKeyLifetime.duration

Integer

Optional

Mutable

The amount of time an issued pairing key can be used until it expires. Can be expressed in minutes or hours. Minimum is one minute, maximum is 48 hours. If the pairingKeyLifetime object is not provided, then 48 hours is used.

applications[].pairingKeyLifetime.timeUnit

String

Optional

Mutable

The time unit for pairingKeyLifetime.duration. Can be MINUTES or HOURS.

applications[].pushLimit.count

Integer

Optional

Mutable

The number of consecutive push notifications that can be ignored or rejected by a user within a defined period before push notifications are blocked for the application. The minimum value is 1 and the maximum value is 50. If this parameter is not provided, the default value is 5.

applications[].pushLimit.lockDuration.duration

Integer

Optional

Mutable

The length of time that push notifications should be blocked for the application if the defined limit has been reached. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 30 minutes.

applications[].pushLimit.lockDuration.timeUnit

String

Optional

Mutable

The time unit for pushLimit.lockDuration.duration. The valid values are MINUTES and SECONDS.

applications[].pushLimit.timePeriod.duration

Integer

Optional

Mutable

The time period in which the push notifications are counted towards the defined limit. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, 10 minutes is used.

applications[].pushLimit.timePeriod.timeUnit

String

Optional

Mutable

The time unit for pushLimit.timePeriod.duration. The valid values are MINUTES and SECONDS.

applications[].newRequestDurationConfiguration.deviceTimeout.duration

Integer

Required

Mutable

The amount of time an authentication request notification has to reach the device before timing out. Minimum is 15 seconds, maximum is 75 seconds.

applications[].newRequestDurationConfiguration.deviceTimeout.timeUnit

String

Required

Immutable

The time unit to use for deviceTimeout.duration. Only valid value is SECONDS.

applications[].newRequestDurationConfiguration.totalTimeout.duration

Integer

Required

Mutable

The total amount of time an authentication request notification has to be handled by the user before timing out. This includes both the time until the notification is displayed to the user and the time the user takes to respond. Minimum is 30 seconds, maximum is 90 seconds. totalTimeout.duration`must exceed `deviceTimeout.duration by at least 15 seconds.

applications[].newRequestDurationConfiguration.totalTimeout.timeUnit

String

Required

Immutable

The time unit to use for totalTimeout.duration. Only valid value is SECONDS.

applications[].push.enabled

Boolean

Required

Mutable

Specifies whether push notification is enabled or disabled for the policy.

applications[].push.numberMatching

Boolean

Optional

Mutable

Set to true if you want to require the authenticating user to select a number that was displayed to them on the accessing device.

applications[].type

String

Required

Immutable

Value must be set to pingIdAppConfig.

enabled

Boolean

Required

Mutable

Whether the device is enabled or disabled in the policy.

ipPairingConfiguration.anyIPAdress

Boolean

Optional

Mutable

If you want to limit users to specific IP addresses when pairing their device, set anyIPAdress to false, and use ipPairingConfiguration.onlyTheseIpAddresses to specify the valid IP addresses.

ipPairingConfiguration.onlyTheseIpAddresses

Array

Optional

Mutable

If you set ipPairingConfiguration.anyIPAdress to false, use onlyTheseIpAddresses to specify the IP addresses from which users can pair their devices. Each item in the array should be an IP address or an address range using CIDR notation, for example, 192.168.0.1/24

otp.failure.coolDown.duration

Integer

Required

Mutable

The amount of time the user is blocked after reaching the maximum number of passcode failures. Can be expressed in seconds or minutes. The minimum is two minutes, and the maximum is 30 minutes. Note that when using the "onetime authentication" feature, the user is not blocked after the maximum number of failures even if you specified a block duration.

otp.failure.coolDown.timeUnit

String

Required

Mutable

The time unit to use for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.

otp.failure.count

Integer

Required

Mutable

The maximum number of times that the OTP entry can fail for a user before they are blocked. The minimum value is 1, maximum is 7.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

PLATFORM and SECURITY_KEY device authentication policy data model (deprecated, replaced by FIDO device)

Property Type Required Mutable Description

enabled

Boolean

N/A

Read-only

Whether the device is enabled or disabled in the policy.

fidoPolicyId

String

N/A

Read-only

The FIDO policy UUID. This property can be null. When null, the environment’s default FIDO Policy is used.

Policy migration data model

Used with the deviceAuthenticationPolicies endpoint and content type: application/vnd.pingidentity.deviceAuthenticationPolicy.fido2.migrate+json for batch conversion of device authentication policies associated with the previous FIDO policy format (device authentication policies that have FIDO Biometrics or Security Key enabled).

Property Type Required Mutable Description

migrationData

Array

Optional

Immutable

List of the objects that must be migrated.

migrationData[].deviceAuthenticationPolicyId

String

Required

Immutable

The UUID of the device authentication policy to migrate. Required if you are providing the migrationData object.

migrationData[].fido2PolicyId

String

Optional

Immutable

The UUID of the enhanced FIDO policy to associate with the device authentication policy. If this parameter is not provided, the default FIDO policy is used.

Device authentication policy errors

In addition to the general error codes, device authentication policy 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 POST or PUT /deviceAuthenticationPolicies request omits a required property or supplies a value that fails validation

Details: must not be null for an omitted device settings object such as sms, must not be blank for an omitted value, sms.otp failure.count should be between <min>..<max> for an out-of-range OTP failure count, sms.otp failure.coolDown.timeUnit should be one of <units> or sms.otp lifeTime.duration should be between <min>..<max> seconds for other OTP configuration values (the same patterns apply to mobile.otp, totp.otp, and whatsApp.otp), rememberMe.web.lifeTime duration must be between [1..129600] minutes for an out-of-range remember-me lifetime, rememberMe.web.lifeTime timeUnit should be one of MINUTES/HOURS/DAYS for an unsupported time unit, mobile.applications[].pushLimit pushLimit.count must be between [1..50] minutes or pushLimit.timePeriod must be between [1..120] minutes for out-of-range push limits, or mobile.applications[].push.numberMatching.enabled must not be null for an omitted number matching flag, for example Validation Error : [sms must not be null]

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT /deviceAuthenticationPolicies request references a FIDO2 policy or notifications policy that does not exist

Details: FIDO2 policy not found: <policyId> with target fido2PolicyId, or Notifications policy not found: <policyId> with target notificationsPolicy.id

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A policy create or update enables a device type that the environment’s license does not support, or enables WhatsApp in an environment without WhatsApp support

Details: Environment is disabled for <DEVICE_TYPE> device with target <deviceType>.enabled (for example, Environment is disabled for FIDO2 device with target fido2.enabled), or a WhatsApp settings error with target whatsApp.enabled

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT /deviceAuthenticationPolicies request uses a policy set name that already exists in the environment

Details: A resource with the specified name already exists. with target name and an existingId inner error identifying the existing policy

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT /deviceAuthenticationPolicies request sets both default and forSignOnPolicy to true, or supplies the deprecated forSignOnPolicy attribute

Details:

Failed to create or update device authentication policy set since default and forSignOnPolicy fields can not both set to true.

with target default,forSignOnPolicy, or Device authentication policy with forSignOnPolicy is deprecated with target forSignOnPolicy

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A batch migration request (application/vnd.pingidentity.deviceAuthenticationPolicy.fido2.migrate+json) cannot migrate the supplied policies

Details: Describes the migration failure with target migrationData

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A DELETE /deviceAuthenticationPolicies request removes the environment’s default policy or a policy that a sign-on policy or other service still references, or a PUT request updates a policy while a PingID to PingOne deployment is in process

Details: Attempt to remove default device authentication policy for environmentId=<envId>, Attempt to remove used device authentication policy for environmentId=<envId> with inner errors naming the referencing services, or Attempt to remove device authentication sign on policy for environmentId=<envId>

400

REQUEST_FAILED

INVALID_PARAMETER

Message: A query string parameter or value is not valid for this request.

When and details

When: A POST or PUT /deviceAuthenticationPolicies request supplies the deprecated securityKey or platform (FIDO Biometrics) settings, disables mobile settings in an environment with PingID, or changes PingID mobile application settings that are immutable

Details: Deprecated Fido Settings: <target> with target securityKey or platform, Mobile settings cannot be disabled in an environment with PingID with target mobile, PingID mobile application Id cannot be changed in Device Authentication Policy settings. with target policy.mobile.applications.id, or PingID mobile Allow pairing cannot be disabled in Device Authentication Policy settings. with target policy.mobile.applications.pairingDisabled

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A PUT /deviceAuthenticationPolicies request disables an authentication method that a PingID authentication policy is currently using

Details:

The following authentication methods cannot be disabled as they are currently being used in at least one PingID authentication policy: <method display names>

(detail code MFA_AUTH_METHODS_CONFLICT) with targets naming the affected <method>.enabled attributes

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

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

When and details

When: The actor lacks the mfa:create:deviceAuthenticationPolicy permission (POST), the mfa:read:deviceAuthenticationPolicy permission (GET), the mfa:update:deviceAuthenticationPolicy permission (PUT), or the mfa:delete:deviceAuthenticationPolicy permission (DELETE)

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

403

ACCESS_FAILED

INVALID_VALUE

Message: The request could not be completed. You do not have access to this resource.

When and details

When: A POST or PUT /deviceAuthenticationPolicies request enables FIDO2 settings in an environment that does not allow them

Details: fido2 settings are not allowed to be enabled in this environment with target fido2Settings

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A device authentication policy operation references a policy or environment that does not exist

Details: None

409

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A DELETE /deviceAuthenticationPolicies request removes an MFA policy that is referenced by an authentication policy

Details: cannot delete MFA policy referenced by authentication policy with target signOnPolicies and a referencedValues inner error listing the referencing authentication policies

429

REQUEST_LIMITED

QUOTA_EXCEEDED

Message: The request will exceed your quota.

When and details

When: A POST /deviceAuthenticationPolicies request creates a policy when the environment’s device authentication policy set limit is already reached

Details: The max number of device authentication policies for this environment has been reached. with a quotaLimit inner error

Device authentication policy events generated

Refer to Audit Reporting Events for the events generated.

Related topics

Multi-factor Authentication (Use Cases)