Jump to

• Request
• Response

Initiate MFA Factor Enrollment With Verification or MFA Factor Enrollment Without Verification

post

/mfa/v1/users/{userGUID}/factors

Request

Supported Media Types

• application/json

Path Parameters

• userGUID: string
  Unique identifier of a user who wants to enroll a factor.

Header Parameters

• Authorization: string
  Provide a valid OAuth Access Token that has the 'MFA Client' scope.

Body ()

Initiate MFA Enrollment Schema

Root Schema : InitiateEnrollment

Type: object

Use this schema to initiate enrollment of MFA factors with or without factor verification. The enrollment is a 2-step process if verification is required. In case of enrollment without verification, it is a single step process.

Show Source

• countryCode(optional): string
  This attribute is considered only if the method is set to SMS or PHONE_CALL.
  This is the international country code that should be prefixed to the mobile number, to be enrolled for SMS or PHONE_CALL.
• method: string
  It indicates the factor or method that the user wants to enroll for MFA. Supported values for this attribute are:

  • SMS
  • PHONE_CALL
  • TOTP
  • PUSH
  • EMAIL
  • SECURITY_QUESTIONS

  
  Depending on the method being enrolled for, additional attributes of this schema may need to be provided.
• mobileNumber(optional): string
  This attribute is considered only if the method is set to SMS or PHONE_CALL.
  This is the mobile number that the user wants to enroll for the SMS or PHONE_CALL factor.
• offlineTOTP(optional): string
  This attribute is considered only if the method is set to TOTP.
  Supported values for this attribute are:
  

  • true
  • false

  A value of 'true' indicates that the user wants to enroll for the offline TOTP factor. By default, the user is enrolled for the online TOTP method if this value is false or is missing.
• otpCode(optional): string
  This attribute is considered only for offline TOTP method and if skipFactorVerification is set to true. If otpCode is provided, the sharedSecret passed is used to generate an otpCode and is validated with the passed otpCode value, before enrolling the TOTP factor.
  
• sharedSecret(optional): string
  Shared Secret of the hardware device or third party provider which has to be enrolled for offline TOTP. This attribute is considered only if skipFactorVerification is set to true.
  
• skipFactorVerification(optional): string
  This attribute indicates that factor verification should be skipped during enrollment.Supported values for this attribute are:
  

  • true
  • false

  
  This attribute is applicable only for SMS, PHONE_CALL, EMAIL and offline TOTP factors.

{
    "type":"object",
    "description":"Use this schema to initiate enrollment of MFA factors with or without factor verification. The enrollment is a 2-step process if verification is required. In case of enrollment without verification, it is a single step process.",
    "required":[
        "method"
    ],
    "properties":{
        "method":{
            "type":"string",
            "description":"It indicates the factor or method that the user wants to enroll for MFA. Supported values for this attribute are:<ul><li>SMS</li><li>PHONE_CALL</li><li>TOTP</li><li>PUSH</li><li>EMAIL</li><li>SECURITY_QUESTIONS</li></ul><br>Depending on the method being enrolled for, additional attributes of this schema may need to be provided."
        },
        "skipFactorVerification":{
            "type":"string",
            "description":"This attribute indicates that factor verification should be skipped during enrollment.Supported values for this attribute are:<br><ul><li>true</li><li>false</li> </ul><br>This attribute is applicable only for SMS, PHONE_CALL, EMAIL and offline TOTP factors."
        },
        "offlineTOTP":{
            "type":"string",
            "description":"This attribute is considered only if the method is set to TOTP.<br>Supported values for this attribute are:<br/><ul><li>true</li><li>false</li></ul>A value of 'true' indicates that the user wants to enroll for the offline TOTP factor. By default, the user is enrolled for the online TOTP method if this value is false or is missing."
        },
        "sharedSecret":{
            "type":"string",
            "description":"Shared Secret of the hardware device or third party provider which has to be enrolled for offline TOTP. This attribute is considered only if skipFactorVerification is set to true.<br>"
        },
        "otpCode":{
            "type":"string",
            "description":"This attribute is considered only for offline TOTP method and if skipFactorVerification is set to true. If otpCode is provided, the sharedSecret passed is used to generate an otpCode and is validated with the passed otpCode value, before enrolling the TOTP factor.<br>"
        },
        "countryCode":{
            "type":"string",
            "description":"This attribute is considered only if the method is set to SMS or PHONE_CALL.<br>This is the international country code that should be prefixed to the mobile number, to be enrolled for SMS or PHONE_CALL."
        },
        "mobileNumber":{
            "type":"string",
            "description":"This attribute is considered only if the method is set to SMS or PHONE_CALL.<br>This is the mobile number that the user wants to enroll for the SMS or PHONE_CALL factor."
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Indicates that the enrollment request was accepted and initiated successfully.

400 Response

Indicates that the request payload is invalid.

401 Response

Indicates that the enrollment request failed due to an invalid token or an inactive or locked user.

404 Response

Indicates that the userGUID provided is invalid.

500 Response

Internal Server error

Back to Top