# Add Step-Up Authentication With the Two-Factor APIs

Learn how to ask a logged in user for another factor before a sensitive action, using the FusionAuth Two-Factor APIs.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

This guide adds a step-up challenge before a sensitive action in your application. The example is a banking application that requires a step-up before a transfer, but not when the user views a balance. For how FusionAuth decides when to require a step-up, and how long a step-up lasts, see [Step-Up Authentication](https://fusionauth.io/docs/authentication/multi-factor-authentication/step-up.md).

## Prerequisites

*   FusionAuth `1.62.0` or later, for the `POST` method of the MFA Status API.
*   A FusionAuth API key with access to the `/api/two-factor` and `/api/two-factor/login` endpoints. For more information, see [API Keys](https://fusionauth.io/docs/apis/authentication.md#managing-api-keys).
*   At least one MFA method enabled on the Tenant. Without one, the MFA Status API never requires a step-up.
*   A server-side session in your application that stores the logged in user's Id.

The steps below send codes by email. Sending codes through FusionAuth requires the Starter plan or higher. On any plan, you can deliver codes through your own channel instead.

The following diagram shows the flow:

```mermaid
sequenceDiagram
    participant User
    participant app as Application
    participant FusionAuth
    User ->> app : View bank balance
    app ->> User : Show bank balance
    User ->> app : Transfer $5,000
    app ->> FusionAuth : Check whether a step-up is required<br/>(MFA Status API)
    FusionAuth ->> app : 242, step-up required
    app ->> FusionAuth : Start the step-up (Start API)
    FusionAuth ->> app : twoFactorId and the user's methods
    app ->> User : Show the user's methods
    User ->> app : Select the email method
    app ->> FusionAuth : Send the code (Send API)
    FusionAuth ->> User : Email with the code
    User ->> app : Enter the code
    app ->> FusionAuth : Complete the step-up<br/>(Complete Multi-Factor API)
    FusionAuth ->> app : 200, with state
    app ->> app : Complete the transfer
    app ->> User : Show confirmation
```

Step-up flow for a bank transfer with an email code.

## Check Whether a Step-Up Is Required

When the user starts a sensitive action, call the [MFA Status API](https://fusionauth.io/docs/apis/two-factor/retrieve-multi-factor-status.md) with an **`action`** of `stepUp`. Put details about the action in **`eventInfo.data`**, so an MFA Requirement Lambda can read them:

Check whether a step-up is required

```shell
API_KEY=...
REQUEST_PAYLOAD='{...}'

curl -XPOST -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'https://local.fusionauth.io/api/two-factor/status' -d "$REQUEST_PAYLOAD"
```

MFA Status request for a step-up

```json
{
  "action": "stepUp",
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "eventInfo": {
    "data": {
      "amount": 5000,
      "operation": "transfer"
    },
    "ipAddress": "192.168.1.42"
  },
  "userId": "429797ba-37d7-4bbe-8748-58fb812448ff"
}
```

When the API returns `200`, skip the remaining steps and complete the action. When the API returns `242`, continue to the next step.

### Skip Low-Risk Actions With a Lambda

> **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/concepts/plans-and-limits/plans-features.md#enterprise-features).

When some actions don't need a step-up, add an [MFA Requirement Lambda](https://fusionauth.io/docs/lambdas/login/mfa-requirement.md) to the Tenant. The following lambda skips the step-up for transfers under 100, and requires a step-up for everything else:

MFA Requirement Lambda that skips small transfers

```javascript
function checkRequired(result, user, registration, context) {
  if (context.action !== 'stepUp') {
    return;
  }

  var data = (context.eventInfo && context.eventInfo.data) || {};
  if (data.operation === 'transfer' && data.amount < 100) {
    result.required = false;
  }
}
```

The lambda returns early for the `login` and `changePassword` actions, so login MFA keeps the Tenant and Application policies.

## Start the Step-Up

Call the [Start Multi-Factor API](https://fusionauth.io/docs/apis/two-factor/start-multi-factor.md):

Start the step-up

```shell
API_KEY=...
REQUEST_PAYLOAD='{...}'

curl -XPOST -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'https://local.fusionauth.io/api/two-factor/start' -d "$REQUEST_PAYLOAD"
```

Start request for a step-up

```json
{
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "state": {
    "transactionId": "9f6a1c2e-3b7d-4e8a-a1f0-5c2d8e4b7a90"
  },
  "trustChallenge": "a1d9e8f6b2c34e7f9a0b5c6d7e8f9a0b1c2d3e4f",
  "userId": "429797ba-37d7-4bbe-8748-58fb812448ff"
}
```

Set the request fields as follows:

*   Put an identifier for the pending action in **`state`**, such as a transaction Id. FusionAuth returns **`state`** when the step-up completes, so your application can match the step-up to the action.
*   When your application needs the [trust token](https://fusionauth.io/docs/authentication/multi-factor-authentication.md#trust-tokens-and-trust-challenges) for the [Change Password API](https://fusionauth.io/docs/apis/users/change-password.md), set **`trustChallenge`** to a long random value. The trust token then only works with the same challenge. For more information, see [Trust Tokens and Trust Challenges](https://fusionauth.io/docs/authentication/multi-factor-authentication.md#trust-tokens-and-trust-challenges).
*   When you deliver the code through your own channel, set **`code`** to your own value, or omit **`code`** and read the generated code from the response.

Start response

```json
{
  "code": "123456",
  "methods": [
    {
      "id": "BD5R",
      "method": "authenticator",
      "name": "Bitwarden Authenticator",
      "authenticator": {
        "algorithm": "HmacSHA1",
        "codeLength": 6,
        "timeStep": 30
      }
    },
    {
      "id": "KLRT",
      "method": "email",
      "name": "Work email",
      "email": "richard@piedpiper.com",
      "lastUsed": true
    },
    {
      "id": "K8RT",
      "method": "email",
      "name": "Personal email",
      "email": "dinesh@piedpiper.com"
    },
    {
      "id": "87KW",
      "method": "sms",
      "name": "Mobile",
      "mobilePhone": "+13035551212"
    }
  ],
  "twoFactorId": "DvnAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}
```

Store the **`twoFactorId`** in the user's server-side session. The `twoFactorId` expires after the Tenant's **Two-Factor** duration, five minutes by default. A new start request for the same user and Application cancels the previous `twoFactorId`.

Show the user the list of **`methods`** and ask the user to choose one. When **`methods`** is empty, the user has no MFA methods. Deliver the code through your own channel instead, and skip the next step.

## Send the Code

When the user chooses an `authenticator` method, skip this step. The user reads the code from the authenticator app.

When the user chooses an `email` or `sms` method, call the [Send API](https://fusionauth.io/docs/apis/two-factor/send-a-multi-factor-code-during-login-or-step-up.md) with the method's **`id`** as **`methodId`**. The Send API needs no API key:

Send the code

```shell
REQUEST_PAYLOAD='{...}'
TWO_FACTOR_ID=... # from the start response

curl -XPOST -H 'Content-type: application/json' 'https://local.fusionauth.io/api/two-factor/send?twoFactorId='$TWO_FACTOR_ID -d "$REQUEST_PAYLOAD"
```

Send request

```json
{
  "methodId": "KLRT"
}
```

The Send API replaces the code from the start request with a new code. Don't call the Send API when you deliver your own code.

## Complete the Step-Up

Build a page that collects the code. Then call the [Complete Multi-Factor Authentication API](https://fusionauth.io/docs/apis/login/complete-mfa.md) with the code and the `twoFactorId`. Set **`noJWT`** to `true`, unless your application needs new tokens. Without **`noJWT`**, FusionAuth issues a new access token and refresh token for every step-up:

Complete the step-up

```shell
API_KEY=...
REQUEST_PAYLOAD='{...}'

curl -XPOST -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'https://local.fusionauth.io/api/two-factor/login' -d "$REQUEST_PAYLOAD"
```

Complete request for a step-up

```json
{
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "code": "915187",
  "ipAddress": "192.168.1.42",
  "noJWT": true,
  "twoFactorId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}
```

The API returns one of the following status codes:

*   `200` when the code is valid. The response includes the user, the **`state`** object, and a **`trustToken`**.
*   `421` when the code is wrong. Ask the user to try again. Failed codes count toward [Account Lockout](https://fusionauth.io/docs/security/account-protection/account-lockout.md).
*   `404` when the `twoFactorId` has expired or was already used. Start a new step-up.
*   `409` when the account is locked. Cancel the action.

For the full list of status codes, see the [Complete Multi-Factor Authentication API](https://fusionauth.io/docs/apis/login/complete-mfa.md).

Complete response for a step-up

```json
{
  "state": {
    "transactionId": "9f6a1c2e-3b7d-4e8a-a1f0-5c2d8e4b7a90"
  },
  "trustToken": "BIjOQVzvVR2Zp6hlRRwnPg1-DlTqSLsTm1W1pmYpzmQ",
  "user": {
    "active": true,
    "email": "richard@piedpiper.com",
    "id": "429797ba-37d7-4bbe-8748-58fb812448ff",
    "lastLoginInstant": 1795017776252,
    "twoFactor": {
      "methods": [
        {
          "email": "richard@piedpiper.com",
          "id": "KLRT",
          "method": "email"
        }
      ]
    },
    "verified": true
  }
}
```

## Complete the Sensitive Action

Before you complete the action, check the following in your application:

1.  The **`user.id`** in the response matches the user in the server-side session.
2.  The **`state`** in the response matches the pending action, such as the transaction Id.
3.  When you allow a step-up to last for a window of time, record the time of the step-up in the server-side session.

Then complete the sensitive action.

## Confirm the Result

To confirm the step-up works, test the following cases:

1.  Start a sensitive action and enter the correct code. The action completes.
2.  Start a sensitive action and enter a wrong code. The API returns `421`, and the action doesn't complete.
3.  Start a sensitive action, wait longer than the **Two-Factor** duration, and enter the code. The API returns `404`.
4.  When you use an MFA Requirement Lambda, start a low-risk action. The MFA Status API returns `200`, and the user sees no challenge.

Related

[Authentication Step-Up Authentication Learn about step-up authentication in FusionAuth, including how to choose an approach and how long a step-up stays valid. step-up authstep-up authenticationmfa](https://fusionauth.io/docs/authentication/multi-factor-authentication/step-up.md)

[APIs Multi-Factor API Learn about the APIs for enabling and disabling multi-factor authentication for users. multi-factor authenticationmfastep-up auth](https://fusionauth.io/docs/apis/two-factor.md)

[APIs Send a Multi-Factor Code During Login or Step Up API API documentation for the FusionAuth Send a Multi-Factor Code During Login or Step Up API. multi-factor authenticationmfastep-up auth](https://fusionauth.io/docs/apis/two-factor/send-a-multi-factor-code-during-login-or-step-up.md)

[APIs Start Multi-Factor API API documentation for the FusionAuth Start Multi-Factor API. multi-factor authenticationmfastep-up auth](https://fusionauth.io/docs/apis/two-factor/start-multi-factor.md)
---

## Other pages in Multi Factor Authentication

> For the full index of this section, see [Authentication](https://fusionauth.io/docs/llms-authentication.txt).

- [Contextual Multi-Factor Authentication (MFA)](https://fusionauth.io/docs/authentication/multi-factor-authentication/contextual.md): Learn about how FusionAuth decides to trigger multi-factor authentication (MFA) in the login flow.
- [Multi-Factor Authentication (MFA)](https://fusionauth.io/docs/authentication/multi-factor-authentication.md): Learn about how to use multi-factor authentication (MFA) in FusionAuth as a developer.
- [Step-Up Authentication](https://fusionauth.io/docs/authentication/multi-factor-authentication/step-up.md): Learn about step-up authentication in FusionAuth, including how to choose an approach and how long a step-up stays valid.
