PingOne Platform APIs

MFA Settings

The MFA settings endpoint supports operations to read, update, and reset the PingOne MFA settings associated with a specified environment. A PUT request lets you manage the maximum number of allowed devices for pairing, and it lets you set the device selection option. A successful DELETE operation resets the MFA settings to the default.

For API operations on a PingID workforce implementation hosted via a PingOne environment, use the PingID APIs instead. Refer to PingID API overview in the PingID API documentation. For more information about using PingID out of PingOne SSO platform, refer to Configuring a multifactor authentication experience using PingOne and PingID.

Maximum allowed devices

The MFA settings property pairing.maxAllowedDevices defines the maximum number of paired MFA devices each user within an environment can have. This can be any number up to 15. The default value is 5. You can update the setting with GET {{apiPath}}/environments/{{envID}}/mfaSettings and reset the setting to its default with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

If the maxAllowedDevices value is decreased below the number of paired devices a user currently has, the user’s existing paired devices remain. After a paired device is deleted though, the user cannot replace it with a new one. This remains true until the number of existing paired devices is below the current value for maxAllowedDevices.

If the maxAllowedDevices limit is reached and the user attempts to create a new device, an error similar to the following is returned.

400 BAD REQUEST
{
  "id": "<errorId>",
  "code": "REQUEST_FAILED",
  "message": "The request could not be completed. There was an issue processing the request.",
  "details": [
    {
      "code": "LIMIT_EXCEEDED",
      "message": "Maximum allowed devices has been reached",
      "innerError": {
        "maximumAllowed": 5
      }
    }
  ]
}

Account lockout

The MFA settings property lockout.failureCount and lockout.durationSeconds defines the maximum number of incorrect MFA authorization actions a user can attempt (such as entering an incorrect OTP or denying a push confirmation on a native device) before the account is locked. The lockout.durationSeconds defines the amount of time after the lockout.failureCount value is exceeded to keep the account in a locked state. You can update the setting with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

For more information about account lockout, refer to User Accounts.

MFA settings data model

Property Type Required? Mutable? Description

lockout

Object

Optional

Mutable

Contains information about the MFA policy lockout settings.

lockout.failureCount

Integer

Optional

Mutable

The maximum number of incorrect authentication attempts before the account is locked.

lockout.durationSeconds

Integer

Optional

Mutable

The number of seconds to keep the account in a locked state.

pairing

Object

Optional

Mutable

Contains information about the MFA policy device pairing settings.

pairing.maxAllowedDevices

Integer

Optional

Mutable

The maximum number of MFA devices each user can have. This can be any number up to 15. The default value is 5. All devices that are Active or Blocked are subject to this limit.

pairing.pairingKeyFormat

String

Optional

Mutable

The type of pairing key issued. The valid values are NUMERIC (12-digit key) and ALPHANUMERIC (16-character alphanumeric key).

phoneExtensions

Object

Optional

Mutable

Contains settings for phone extension support.

phoneExtensions.enabled

Boolean

Optional

Mutable

Set to true to allow one-time passwords to be delivered via voice to phone numbers that include extensions. Set to false to disable support for phone numbers with extensions. By default, support for extensions is disabled.

updatedAt

Date

N/A

Read-only

When the resource was last updated.

users

Object

Optional

Mutable

Contains information about the default settings for new users.

users.mfaEnabled

Boolean

Optional

Mutable

Set mfaEnabled to true if you want MFA to be enabled by default for new users.

The default method to use for MFA is now set at the MFA policy level rather than at the environment level. For backward compatibility reasons, authentication.deviceSelection is still included in the responses when reading, updating, or resetting the MFA settings for the environment. However, if you want to modify this setting, you must use the deviceAuthenticationPolicies endpoint.

Response codes

Code Message

200

Successful operation.

400

The request could not be completed.

401

You do not have access to this resource.

404

The requested resource was not found.

You need the Environment Admin role to read MFA settings resources.