Step-Up MFA API Reference

The Step-Up MFA APIs can be called from your backend using your PropelAuth API Key. These APIs are not required for your users to login with MFA and are instead to be used when you want to require a user to verify their MFA for a specific action within your application.

Check out the Step-Up MFA documentation for more information on how to use these APIs.

POST/api/backend/v1/mfa/step-up/verify-totp

Verify TOTP Challenge

Verifies a user's TOTP code and returns a step-up grant if successful. The user must have MFA enabled before this endpoint can be used. See the Step-Up MFA Guide for more information.

Properties

Name
actionType *
Type
string
Description
Any string you want, such as `SENSITIVE_ACTION`. This is used to identify the action that the user is trying to perform. It must match the action_type that will be used when verifying the user's Step-Up Grant.
Name
userId *
Type
string
Description
The ID of the user.
Name
code *
Type
string
Description
The code from the user's TOTP app. This is usually a 6-digit number.
Name
grantType *
Type
string
Description
Must equal either "ONE_TIME_USE" or "TIME_BASED". This is used to identify the type of grant that you want to create.
Name
validForSeconds *
Type
number
Description
The number of seconds that the grant should be valid for.

Request

auth.verifyStepUpTotpChallenge({
    actionType: "SENSITIVE_ACTION",
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    code: "123456",
    grantType: "TIME_BASED",
    validForSeconds: 60
});

Successful Response

{ 
    "stepUpGrant": "f374f738cc..."
}

POST/api/backend/v1/mfa/step-up/verify-grant

Verify Step-Up Grant

Verifies a user's MFA Grant created by the Verify TOTP Code API. The user must have MFA enabled before this endpoint can be used. See the Step-Up MFA Guide for more information.

Properties

Name
actionType *
Type
string
Description
Any string you want, such as `SENSITIVE_ACTION`. This is used to identify the action that the user is trying to perform. It must match the action_type that was used when verifying the user's TOTP code.
Name
userId *
Type
string
Description
The ID of the user.
Name
grant *
Type
string
Description
The step-up grant returned from the Verify TOTP Code API.

Request

auth.verifyStepUpGrant({
    actionType: "SENSITIVE_ACTION",
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    grant: "f374f738cc..."
});

Successful Response

{
    "success": true
}