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.

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 /environments/{{envID}}/mfaSettings and reset the setting to its default with PUT /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 /environments/{{envID}}/mfaSettings.

For more information about account lockout, see User Accounts.

MFA settings data model {#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.

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.