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

Required Permissions

Read Users

Properties

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

Request

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

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

auth.user().fetch_user_mfa_methods(FetchUserMfaMethodsParams {
    user_id: "31c41c16-c281-44ae-9602-8a047e3bf33d".to_string()
})

auth.FetchUserMfaMethods(uuid.MustParse("31c41c16-c281-44ae-9602-8a047e3bf33d"))

curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/user/<user_id>/mfa"

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..."\
            }\
        ]
    }
}

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.

Required Permissions

Step-up 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 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. Max 3600 seconds (1 hour).

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

Required Permissions

Step-up 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.
• 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".
• 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..."
}

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.

Required Permissions

Step-up MFA

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.

Request

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

Successful Response

{
    stepUpGrant: "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.

Required Permissions

Step-up MFA

Properties

• Name actionType *Type string Description Any string you want, such as SENSITIVE_ACTION.
• 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
}