Logo

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.

GET/api/backend/v1/user/<user_id>>/mfa

Fetch User MFA Methods

Returns which type of MFA (TOTP or SMS) the user is enrolled in. See the Step-Up MFA Guide for more information.

Properties

  • Name
    userId *
    Type
    string
    Description
    The ID of the user.

Request

auth.fetchUserMfaMethods("31c41c16-c281-44ae-9602-8a047e3bf33d")

Successful Response

// if TOTP MFA
{
    mfaSetup: {
        type: "Totp"
    }
}

// if SMS MFA
{
    mfaSetup: {
        type: "Phone",
        phone_numbers: [
            {
                mfa_phone_number_suffix: "1234",
                mfa_phone_id: "cc83af74-cd..."
            },
            {
                mfa_phone_number_suffix: "5678",
                mfa_phone_id: "4d01e8ac-2c..."
            }
        ]
    }
}
# if TOTP MFA
{
    mfa_setup: {
        type: "Totp"
    }
}

# if SMS MFA
{
    mfa_setup: {
        type: "Phone",
        phone_numbers: [
            {
                mfa_phone_number_suffix: "1234",
                mfa_phone_id: "cc83af74-cd..."
            },
            {
                mfa_phone_number_suffix: "5678",
                mfa_phone_id: "4d01e8ac-2c..."
            }
        ]
    }
}
// if TOTP MFA
FetchUserMfaMethodsResponse {
    mfa_setup: {
        type: "Totp"
    }
}

// if SMS MFA
FetchUserMfaMethodsResponse {
    mfa_setup: {
        type: "Phone",
        phone_numbers: [
            {
                mfa_phone_number_suffix: "1234",
                mfa_phone_id: "cc83af74-cd..."
            },
            {
                mfa_phone_number_suffix: "5678",
                mfa_phone_id: "4d01e8ac-2c..."
            }
        ]
    }
}
// if TOTP MFA
FetchUserMfaMethodsResponse {
    MfaSetup: {
        Type: "Totp"
    }
}

// if SMS MFA
FetchUserMfaMethodsResponse{
    MfaSetup: {
        Type: "Phone",
        PhoneNumbers: [
            {
                MfaPhoneNumberSuffix: "1234",
                MfaPhoneID: "cc83af74-cd..."
            },
            {
                MfaPhoneNumberSuffix: "5678",
                MfaPhoneID: "4d01e8ac-2c..."
            }
        ]
    }
}
// if TOTP MFA
{
    "mfa_setup": {
        "type": "Totp"
    }
}

// if SMS MFA
{
    "mfa_setup": {
        "type": "Phone",
        "phone_numbers": [
            {
                "mfa_phone_number_suffix": "1234",
                "mfa_phone_id": "cc83af74-cd..."
            },
            {
                "mfa_phone_number_suffix": "5678",
                "mfa_phone_id": "4d01e8ac-2c..."
            }
        ]
    }
}
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..."
}
{ 
    step_up_grant: "f374f738cc..."
}
VerifyTotpChallengeResponse { 
    step_up_grant: "f374f738cc..."
}
VerifyTotpChallengeResponse { 
    StepUpGrant: "f374f738cc..."
}
{ 
    "step_up_grant": "f374f738cc..."
}
POST/api/backend/v1/mfa/step-up/phone/send

Send SMS MFA Code

Initiates the process to send an SMS MFA code for Step-Up MFA. See the Step-Up MFA Guide for more information on Step-Up MFA and SMS MFA Documentation on how to setup SMS MFA.

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
    mfaPhoneId *
    Type
    string
    Description
    The ID of the phone retrieved from the Fetch User MFA Methods API.
  • 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.sendSmsMfaCode({
    actionType: "SENSITIVE_ACTION",
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    mfaPhoneId: "38497dea-4d6...",
    grantType: "TIME_BASED",
    validForSeconds: 60
});

Successful Response

{
    challengeId: "a7b0e75b-3a..."
}
{
    challenge_id: "a7b0e75b-3a..."
}
SendSmsCodeResponse {
    challenge_id: "a7b0e75b-3a..."
}
SendSmsMfaCodeResponse {
    ChallengeID: "a7b0e75b-3a..."
}
{
    "challenge_id": "a7b0e75b-3a..."
}
POST/api/backend/v1/mfa/step-up/phone/verify

Verify SMS Challenge

Verifies a user's MFA challenge and code created by the Send SMS MFA 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
    challengeId *
    Type
    string
    Description
    The Challenge ID generated by the Send SMS MFA Code API.
  • Name
    userId *
    Type
    string
    Description
    The ID of the user.
  • Name
    code *
    Type
    string
    Description
    The code from the SMS. This is usually a 6-character string.

Request

auth.verifySmsChallenge({
    challengeId: "38497dea-4d6..",
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    code: "123456",
});

Successful Response

{
    stepUpGrant: "f1d402e7679197..."
}
{
    step_up_grant: "f1d402e7679197..."
}
VerifySmsChallengeResponse {
    step_up_grant: "f1d402e7679197..."
}
VerifySmsChallengeResponse{
    StepUpGrant: "f1d402e7679197..."
}
{
    "step_up_grant": "f1d402e7679197..."
}
POST/api/backend/v1/mfa/step-up/verify-grant

Verify Step-Up Grant

Verifies a user's MFA Grant created by either the Verify TOTP Code or Verify SMS Challenge APIs. 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 in either the Verify TOTP Challenge or Send SMS MFA Code APIs.
  • Name
    userId *
    Type
    string
    Description
    The ID of the user.
  • Name
    grant *
    Type
    string
    Description
    The step-up grant returned from either the Verify TOTP Code or Verify SMS Challenge APIs.

Request

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

Successful Response

{
    success: true
}
True
VerifyStepUpGrantResponse {
    success: true,
}
{
    "success": true
}, nil
{}