Set Users MFA Type

Sets the multi-factor authentication (MFA) type for the specified users. The target users must have MFA enabled. This REST API supports partial failure. If the type cannot be changed for any users, the failures parameter returns the identifier, login name, and failure reason for those users.

Required Permissions

Requires the ADMIN role or higher.

HTTP Request

cURL Example

curl -H "Authorization: Bearer <API_KEY>" \
     -d guids="GUID1,GUID2,GUIDN" \
     -d type=OTP \
     -X POST https://HOSTNAME/api/sonar/users/mfa/type

Request Parameters

MFA types

• OTP: Verification code from an OTP app such as Google Authenticator
• MAIL: Verification code sent by email (requires mail server configuration)
• SMS: Verification code sent by SMS
• PASSWORD: Additional password input

Success Response

Successful Request

{
  "failures": []
}

• failures (Array): Failure details for users whose MFA type could not be set
  • id (String): GUID of the user
  • login (String): Login name of the user. Omitted when the user is not found
  • reason (String): Failure reason

Partial Successful Request

{
  "failures": [
    {
      "id": "ffaf431b-653a-4329-8f83-913cbb00342d",
      "login": "gildong",
      "reason": "mfa-not-enabled"
    }
  ]
}

Error Responses

Required argument is missing

HTTP status code 400

{
  "error_code": "null-argument",
  "error_msg": "guids should be not null"
}

User identifier is not in valid GUID format

HTTP status code 400

{
  "error_code": "invalid-param-type",
  "error_msg": "guids should be guid type."
}

Unsupported MFA type

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "not-support-mfa-type"
}

No administrator privileges

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "no-permission"
}

User is not found

HTTP status code 200

{
  "failures": [
    {
      "id": "6ba6031e-9d03-4a2b-8372-20ceee8f2a75",
      "reason": "user-not-found"
    }
  ]
}

Apply to a user with higher privileges

HTTP status code 200

{
  "failures": [
    {
      "id": "ffaf431b-653a-4329-8f83-913cbb00342d",
      "login": "admin",
      "reason": "no-permission"
    }
  ]
}

MFA is not enabled

HTTP status code 200. The target user must have MFA enabled before the MFA type can be changed.

{
  "failures": [
    {
      "id": "ffaf431b-653a-4329-8f83-913cbb00342d",
      "login": "gildong",
      "reason": "mfa-not-enabled"
    }
  ]
}