# 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](https://docs.propelauth.com/overview/authentication/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](https://docs.propelauth.com/overview/authentication/step-up-mfa) for more information on how to use these APIs.

* * *

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

## [Fetch User MFA Methods](https://docs.propelauth.com/reference/api/mfa#fetch-user-mfa-methods)

Returns which type of MFA (TOTP or SMS) the user is enrolled in. See the [Step-Up MFA Guide](https://docs.propelauth.com/overview/authentication/step-up-mfa) for more information.

### Required Permissions

Read Users

### Properties

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

### Request

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

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

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

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

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

### Successful Response

```javascript
// 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](https://docs.propelauth.com/reference/api/mfa#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](https://docs.propelauth.com/overview/authentication/step-up-mfa) 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](https://docs.propelauth.com/reference/api/mfa#verify-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

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

### Successful Response

```javascript
{
    stepUpGrant: "f374f738cc..."
}
```

* * *

POST/api/backend/v1/mfa/step-up/phone/send

## [Send SMS MFA Code](https://docs.propelauth.com/reference/api/mfa#send-sms-mfa-code)

Initiates the process to send an SMS MFA code for Step-Up MFA. See the [Step-Up MFA Guide](https://docs.propelauth.com/overview/authentication/step-up-mfa) for more information on Step-Up MFA and [SMS MFA Documentation](https://docs.propelauth.com/overview/authentication/mfa#sms-mfa) 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

```javascript
auth.sendSmsMfaCode({
    actionType: "SENSITIVE_ACTION",
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    mfaPhoneId: "38497dea-4d6...",
    grantType: "TIME_BASED",
    validForSeconds: 60
});
```

### Successful Response

```javascript
{
    challengeId: "a7b0e75b-3a..."
}
```

* * *

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

## [Verify SMS Challenge](https://docs.propelauth.com/reference/api/mfa#verify-sms-challenge)

Verifies a user's MFA challenge and code created by the [Send SMS MFA Code](https://docs.propelauth.com/reference/api/mfa#send-sms-mfa-code) API. The user must have MFA enabled before this endpoint can be used. See the [Step-Up MFA Guide](https://docs.propelauth.com/overview/authentication/step-up-mfa) 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](https://docs.propelauth.com/reference/api/mfa#send-sms-mfa-code).
- Name `userId`  *Type string  Description The ID of the user.
- Name `code`  *Type string  Description The code from the SMS.

### Request

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

### Successful Response

```javascript
{
    stepUpGrant: "f1d402e7679197..."
}
```

* * *

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

## [Verify Step-Up Grant](https://docs.propelauth.com/reference/api/mfa#verify-step-up-grant)

Verifies a user's MFA Grant created by either the [Verify TOTP Code](https://docs.propelauth.com/reference/api/mfa#verify-totp-challenge) or [Verify SMS Challenge](https://docs.propelauth.com/reference/api/mfa#verify-sms-challenge) APIs. The user must have MFA enabled before this endpoint can be used. See the [Step-Up MFA Guide](https://docs.propelauth.com/overview/authentication/step-up-mfa) 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](https://docs.propelauth.com/reference/api/mfa#verify-totp-challenge) or [Verify SMS Challenge](https://docs.propelauth.com/reference/api/mfa#verify-sms-challenge) APIs.

### Request

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

### Successful Response

```javascript
{
    success: true
}
```