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.

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.

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

MFA settings errors

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

Message: Validation Error : [pairing.maxAllowedDevices must not be null]

When and details

When: A PUT /mfaSettings request omits the required pairing.maxAllowedDevices property

Details: must not be null for an omitted pairing.maxAllowedDevices (detail EMPTY_VALUE)

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /mfaSettings request supplies a pairing.maxAllowedDevices value outside 1-20, a lockout.failureCount value outside 1-100, a lockout.durationSeconds value outside 1-86400, or an unrecognized pairing.pairingKeyFormat

Details: must be less than or equal to 20 or must be greater than or equal to 1 for pairing.maxAllowedDevices, must be less than or equal to 100 or must be greater than or equal to 1 for lockout.failureCount, must be less than or equal to 86400 or must be greater than or equal to 1 for lockout.durationSeconds, or invalid value for pairing.pairingKeyFormat, for example Validation Error : [pairing.pairingKeyFormat invalid value]

400

INVALID_REQUEST

INVALID_VALUE

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

When and details

When: A PUT /mfaSettings request body cannot be deserialized

Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message:

The MFA settings could not be updated because a deployment of PingID to PingOne is also in process. Try again in a few minutes.
When and details

When: A PUT or DELETE /mfaSettings request from an actor who is not authorized for the platform runs while a PingID deployment to PingOne is in progress for the environment

Details: None

403

ACCESS_FAILED

None

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

When and details

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

Details: None

403

ACCESS_FAILED

None

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

When and details

When: A PUT /mfaSettings request sets pairing.pairingKeyFormat to ALPHANUMERIC (or any value other than NUMERIC) in an environment where PingID is fully deployed through PingOne

Details: None