Start Multi-Factor API

On this page

Starts an multi-factor request. This would be used for only step up auth, such as when sensitive data is requested.

If you want to provide your own code and/or deliver the code out of band using your own delivery mechanism, this is the right API call. Do not combine this with a Send a Multi-Factor Code During Login or Step Up call, as calling that API will invalidate all other codes associated with the twoFactorId, including any you provide.

To require additional factors during login, Enable Multi-Factor for the User. Then FusionAuth will handle MFA code collection automatically, if you are using the hosted login pages, or send a status code in response to the login API if you are not.

Request#

Start multi-factor authentication

POST/api/two-factor/start

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantId

Type: String
Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon other values in the request or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body#

applicationId

Type: UUID
Optional

An application Id. If this is not provided and there are multiple tenants, the X-FusionAuth-TenantId header is required.

code

Type: String
Optional

A valid Multi-Factor verification code. When this value is omitted, one will be generated.

Providing a code allows you to choose an alternative delivery mechanism if needed, such as a chat message. It also allows you to to specify a code string that meets your needs.

Do not provide the code if the user is expected to use an authenticator/TOTP MFA method.

loginId

Type: String

The login identifier of the user. The login identifier can be one of the following (see loginIdTypes for information on which of these identifiers will be used):

Email address
Phone number (if phoneNumber is included in loginIdTypes)
Username

This field is marked optional, but you must provide either the loginId or the userId to complete this API. If both fields are provided in the request body, the userId will be utilized. Prior to version 1.33.0, this field was always required because the userId was not available as an option.

loginIdTypes

Type: Array<String>
Optional
Defaults to [email, username]
Available since 1.59.0

The identity types that FusionAuth will compare the loginId to. Can be one or more of the following:

email
phoneNumber
username

Note

The order is significant. If ["email", "username"] is supplied with a loginId value of terry@example.com, then a user with terry@example.com as their email address will match first before any user with terry@example.com as their username.

state

Type: Object
Optional

Additional data to be passed through this Multi-Factor request. After successful login, the state field in the response will contain this data.

trustChallenge

Type: String
Optional
Available since 1.33.0

This value may be used to bind a Two-Factor login request to a particular trusted action.

For example, if you are using this API to complete a Two-Factor Login in order to obtain a trustToken you may optionally provide this value to bind this request to the intended usage of the trustToken returned in the API response.

userId

Type: UUID
Optional
Available since 1.33.0

The unique User Id of the User.

This field is marked optional, but you must provide either the loginId or the userId to complete this API. If both fields are provided in the request body, the userId will be utilized.

Example Request JSON

{
  "loginId": "richard@piedpiper.com",
  "applicationId": "10000000-0000-0002-0000-000000000001",
  "code": "123456",
  "state": {
    "redirect_uri": "https://fusionauth.io"
  }
}

Response#

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The User does not exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

code

Type: String

A valid Multi-Factor verification code.

methods

Type: Array

A list of configured authentication methods. This field will be omitted if none have been configured.

methods[x].id

Type: String

The identifier for this method.

methods[x].name

Type: String
Optional
Available since 1.68.0

The display name for this method.

methods[x].lastUsed

Type: Boolean

true if this method was used most recently.

methods[x].method

Type: String

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

methods[x].authenticator

Type: Object

An object with additional configuration for TOTP authentication methods. Only present if methods[x].method is authenticator.

methods[x].authenticator.algorithm

Type: String

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1. The possible values are:

HmacSHA1
HmacSHA256
HmacSHA512

methods[x].authenticator.codeLength

Type: Integer

The length of code generated by the TOTP. With the current implementation, this will always be 6.

methods[x].authenticator.timeStep

Type: Integer

The time-step size in seconds. With the current implementation, this will always be 30.

methods[x].email

Type: String

The value of the email address for this method. Only present if methods[x].method is email.

methods[x].mobilePhone

Type: String

The value of the mobile phone for this method. Only present if methods[x].method is sms.

twoFactorId

Type: String

A value to be provided to the Login endpoint to complete Multi-Factor login or the Send endpoint to send a code.

Example Response JSON With Methods Configured

{
  "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"
}

Example Request JSON With No Methods Configured

{
  "code": "123456",
  "twoFactorId": "DvnAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}

APIs

Learn about the APIs for enabling and disabling multi-factor authentication for users.

fusionauth apirest apihttp api

APIs

API documentation for the FusionAuth Send a Multi-Factor Code During Login or Step Up API.

fusionauth apirest apihttp api

APIs

API documentation for the FusionAuth Disable Multi-Factor API.

fusionauth apirest apihttp api

APIs

API documentation for the FusionAuth Enable Multi-Factor API.

fusionauth apirest apihttp api