Manage MFA

All the MFA APIs require the following request parameter:

1. Get all Current Authenticated User's MFA Factor Registrations

This GET method is used by the authenticated user to retrieve all their MFA factor registrations.

Request Example

curl --location GET '{{url}}/api/mfa/registrations' \
--header 'Accept: application/json'

Response Example

Status: 200 OK

[
  {
    "status": "CHALLENGE",
    "factor": "TOTP",
    "additionalDetails": {
      "additionalProp1": {}
    }
  }
]

2. Register the Current Authenticated User for the MFA factor

This POST method registers the authenticated user for a MFA factor.

Request Example

curl --location POST '{{url}}/api/mfa/register/TOTP' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ' {
  "additionalProp1": {}
}'

Response Example

{
  "status": "CHALLENGE",
  "factor": "TOTP",
  "additionalDetails": {
    "additionalProp1": {}
  }
}

3. Get the Current Authenticated User's MFA Factor Registration Details

This GET method is used by the authenticated user to retrieve their MFA factor registration details.

Request Example

curl --location GET '{{url}}/api/mfa/register/TOTP' \
--header 'Accept: application/json'

Response Example

{
  "status": "CHALLENGE",
  "factor": "TOTP",
  "additionalDetails": {
    "additionalProp1": {}
  }
}

4. Delete the current authenticated user's MFA factor registration

This DELETE method deletes the current authenticated user's MFA registration.

Request Parameters

The request parameter used in this method is shown in the following table:

Request Example

curl --location --request DELETE '{{url}}/api/mfa/register/TOTP/<string>' \
--header 'Accept: application/json'

Response Example

{ 
   "message": "<string>", 
   "errorCode": "<string>"
}

5. Get MFA factor Registration Details for a User

This GET method is used by tenant administrators to retrieve the MFA factor registration details for the given target user.

Note: Only administrators can execute this API.

Request Parameters

The request parameter used in this method is shown in the following table:

Request Example

curl --location GET '{{url}}/api/mfa/admin/registrations/TOTP/users/<string>' \
--header 'Accept: application/json'

Response Example

[
  {
    "status": "CHALLENGE",
    "factor": "TOTP",
    "additionalDetails": {
      "additionalProp1": {}
    }
  }
]

6. Delete MFA factor registration details

This DELETE method deletes all MFA factor registrations for the given target user.

Note: Only administrators can execute this API.

The request parameter used in this method is shown in the following table:

Request Example

curl --location --request DELETE '{{url}}/api/mfa/admin/registrations/TOTP/users/<string>'

Status: 204 No Content

7. Delete MFA factor registered credentials

This DELETE method deletes all MFA factor registered credentials.

Note: Only administrators can execute this API.

The request parameter used in this method is shown in the following table:

Request Example

curl --location --request DELETE '{{url}}/api/mfa/admin/registrations/TOTP/users/<string>'

Status: 204 No Content

Manage Users

1. Users with view access to identities can retrieve another user’s TOTP registration status

This GET method returns the user's TOTP registration status.

Request Example

curl --location --request GET '{{url}}/api/mfa/admin/registrations/{factor}/users/{targetUserId}'

Response Example

{   
    "status": "REGISTERED",    
    "factor": "TOTP"
}

2. Users with Manage Access to Identities can delete/unregister another user’s TOTP registration

This GET method is used by users who have managed access to delete or unregister another user's TOPT registration. 

Request Example

curl --location --request GET '{{url}}/api/mfa/admin/registrations/{factor}/users/{targetUserId}'

Response Example

{
    "status": "REGISTERED",
    "factor": "TOTP"
}

Status: 204 No Content

Register and View Step Up MFA TOTP Factor

1. Create a New Secret Key for OTP Generations 

This POST method creates a new secret key for OTP generations.

Request Example

curl --location --request POST
{    
   "action": "GENERATE_SECRET"
} 

Response Example

{   
 "status": "CHALLENGE",   
 "factor": "TOTP",    
 "additionalDetails": 
 {        
   "registrationStatus": "CHALLENGE",        "key": 
   "K5WWKYUNX3KWCDVF7CN2RYP7IBPTGYNS",        "uri": 
   "otpauth://totp/Britive:ymwmacdev-yiumen.wong@britive.com? 
secret=K5WWKYUNX3KWCDVF7CN2RYP7IBPTGYNS&issuer=Britive&algorithm=SHA512&digits=6&period=30"    
 }
}

2. Get MFA TOTP Registration Status

This GET method returns the MFA TOTP registration status.

Request Example

curl --location --request GET '{{url}}/api/mfa/register/TOTP'

Response Example

{    
   "status": "REGISTERED",    
   "factor": "TOTP"
}