Jump to

• Request
• Response
• Examples

Change Default MFA Factor or Un-Enroll in MFA

patch

/mfa/v1/users/{userGUID}

Request

Supported Media Types

• application/json

Path Parameters

• userGUID: string
  Unique identifier for User

Header Parameters

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

Body ()

Change Default Factor or Unenroll MFA Schema

Root Schema : ChangeDefaultFactor

Type: object

Use this schema to change default factor or to unenroll MFA factors

Show Source

• disableMFA(optional): string
  This attribute indicates that the user wants to disable MFA from his profile. This removes all enrolled factors from a user's profile. Supported values for this attribute are:
  

  • true
  • false

  This should only be invoked by a user who is already enrolled for MFA.
• preferredFactorId(optional): string
  This attribute contains the unique identifier of an enrolled factor that the user wants to set as his default MFA factor. In case of SECURITY_QUESTIONS method, this attribute should have it's value set to -'SecurityQuestions'
• preferredMethod(optional): string
  This attribute indicates the MFA method that the user wants to set as his default method of authentication. Supported values for this attribute are:

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

  
  When a user wants to change his default MFA factor, this attribute also needs the preferredFactorId attribute to be provided.

{
    "type":"object",
    "description":"Use this schema to change default factor or to unenroll MFA factors",
    "properties":{
        "disableMFA":{
            "type":"string",
            "description":"This attribute indicates that the user wants to disable MFA from his profile. This removes all enrolled factors from a user's profile. Supported values for this attribute are:<br><ul><li>true</li><li>false</li> </ul>This should only be invoked by a user who is already enrolled for MFA."
        },
        "preferredFactorId":{
            "type":"string",
            "description":"This attribute contains the unique identifier of an enrolled factor that the user wants to set as his default MFA factor. In case of SECURITY_QUESTIONS method, this attribute should have it's value set to -'SecurityQuestions'"
        },
        "preferredMethod":{
            "type":"string",
            "description":"This attribute indicates the MFA method that the user wants to set as his default method of authentication. 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>When a user wants to change his default MFA factor, this attribute also needs the preferredFactorId attribute to be provided."
        }
    }
}

Back to Top

Response

200 Response

Indicates successful profile update.

400 Response

Indicates that the request payload is invalid.

401 Response

Indicates that the profile update request failed due to an invalid token, or an inactive or locked user, or if the user hasn't enrolled in any MFA factors.

404 Response

Indicates that the userGUID provided is invalid.

500 Response

Internal Server error

Back to Top

Examples

The following example shows how to change the default factor or un-enroll in MFA by submitting a PATCH request on the REST resource using cURL. For more information about cURL, see Use cURL.

Note:

There is an Oracle Identity Cloud Service Factor Enrollment Postman collection available. Download the collection and example environment with variables from the idcs-factor-enrollment-api folder within GitHub and import them into a REST client.

cURL Command

Note:

The command in this example uses the URL structure https://tenant-base-url/resource-path, where tenant-base-url represents the Identity Service URL, and the resource path represents the Identity Service API. See Send Requests for the appropriate URL structure to use.

The following request and response examples are included for this API:

• Example of a Request Body When Changing the Default Factor

• Example of a Response Body When Changing the Default Factor

• Example of a Request Body When Un-Enrolling in MFA

• Example of a Response Body When Un-Enrolling in MFA

• Error Response Examples

curl
-X PATCH
-H "Content-Type:application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
https://tenant-base-url/mfa/v1/users/{userGUID}

Example of a Request Body When Changing the Default Factor

The following example shows the contents of the request body in JSON format when a user wants to change their default factor:

{
    "preferredFactorId":"{{factorID}}",
    "preferredMethod":"TOTP/EMAIL/PUSH/SMS"
}

Example of a Response Body When Changing the Default Factor

The following example shows the contents of the response body in JSON format when a user wants to change their default factor:

{
    "status": "success"
}

Example of a Request Body When Un-Enrolling in MFA

The following example shows the contents of the response body in JSON format when a user wants to un-enroll in MFA:

{
   "disableMFA": true
}

Example of a Response Body When Un-Enrolling in MFA

The following example shows the contents of the response body in JSON format a user wants to un-enroll in MFA:

{
    "status": "success"
}

Error Response Examples

The following example shows the contents of the response body in JSON format when the userGUID is invalid:

{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

The following example shows the contents of the response body in JSON format when the user isn't enrolled in MFA:

{
    "status": "failed",
    "ecId": "0000Mif1RDW2800000J",
    "cause": [
        {
            "code": "AUTH-1131",
            "message": "The user is not authorized to perform this action, since has not enrolled for any MFA factors."
        }
    ]
}

Back to Top