Start Multi-Factor

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-TenantIdStringoptional

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 the request parameters 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#

applicationIdUUIDoptional

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

codeStringoptional

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.

loginIdString

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.

loginIdTypesArray<String>optionalDefaults 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

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.

stateObjectoptional

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

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

userIdUUIDoptionalAvailable 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#

codeString

A valid Multi-Factor verification code.

methodsArray

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

methods[x].idString

The identifier for this method.

methods[x].nameStringoptionalAvailable since 1.68.0

The display name for this method.

methods[x].lastUsedBoolean

true if this method was used most recently.

methods[x].methodString

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].authenticatorObject

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

methods[x].authenticator.algorithmString

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

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

methods[x].authenticator.timeStepInteger

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

methods[x].emailString

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

methods[x].mobilePhoneString

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

twoFactorIdString

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