The MFA settings endpoint supports operations to read, update, and reset the 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 mobile 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.

Properties

Property Description
authentication An object that contains the device selection settings.
authentication.deviceSelection Mutable A string that defines the device selection method. Options are DEFAULT_TO_FIRST (this is the default setting) and PROMPT_TO_SELECT.
lockout An object that contains lockout settings.
lockout.failureCount Mutable An integer that defines the maximum number of incorrect authentication attempts before the account is locked.
lockout.durationSeconds Mutable An integer that defines the number of seconds to keep the account in a locked state.
pairing An object that contains pairing settings.
pairing.maxAllowedDevices Mutable An integer that defines the maximum number of MFA devices each user can have. This can be any number up to 15. The default value is 5. For more information, see Maximum allowed devices.
updatedAt Read-only

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.