Manage MFA

All the MFA APIs require the following request parameter:

1. Register the Current Authenticated User for the MFA factor

This POST method is used to register the authenticated user for a MFA factor.

Request Example

curl --location 'https://localhost/api/mfa/register/TOTP' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ' { 
    "action": "GENERATE_SECRET" }'

Response Example

{    
   "status": "CHALLENGE",  
   "factor": "TOTP",   
   "additionalDetails": 
  {        
      "key": "SPE6SOTTGB7SYXQMXMNUKBCRO3PHT6YN",        "uri": 
      "otpauth://totp/Britive:qa4-bgprasad?secret=SPE6SOTTGB7SYXQMXMNUKBCRO3PHT6YN&issuer=Britive&algorithm=SHA1&digits=6&period=30"    
   }
}

2. 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.

Request Example

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

Response Example

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

3. 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 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 '{{url}}/api/mfa/admin/registrations/TOTP/users/<string>' \
--header 'Accept: application/json'

Response Example

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

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

This DELETE method is used to delete the MFA factor registration details for the user.

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. Delete MFA factor registration details

This DELETE method js used to delete the MFA factor registration details.

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>'

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 manage 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"
}