/Docs

Multi-Factor API

Email and phone multi-factor methods are only available in a paid plan of FusionAuth. Please visit our pricing page to learn more about paid plans.

This API controls multi-factor authentication (MFA) options.

Authentication#

Some of these operations can use JWT authentication instead of API key authentication. In some cases, when you have a valid twoFactorId, neither a JWT nor an API key is required.

Learn more about JWT authentication and see examples here.

TOTP Implementation#

Support for Authy, Google Authenticator and other time based one-time password solutions are not premium features and are included in the Community plan.

While there is underlying support for different code lengths, algorithms and time steps, at the current time the system only allows for the following TOTP settings:

Configuration settingCurrently allowed value
authenticator.algorithmHmacSHA1
authenticator.codeLength6
authenticator.timeStep30

Any attempt to change these configuration values will currently be ignored. If you need different configuration settings, please file a GitHub issue detailing your use case.

Enable Multi-Factor#

This API is used to enable Multi-Factor authentication for a single User. To use this API the User must provide a valid Multi-Factor verification code.

If using message based delivery, you may Send a Multi-Factor Code When Enabling MFA to deliver a code to the User. The User will then provide this code as input.

Request#

API Key Authentication
Enable Multi-Factor Authentication by User Id
POST/api/user/two-factor/{userId}

Request Parameters#

userIdUUIDrequired

The Id of the User for whom to enable Multi-Factor authentication.

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. This parameter is optional, and when provided it will cause application specific configuration to be used when available.

For example, to use an application specific email template to notify the user when multi-factor has been enabled, this parameter will be required. When this parameter is omitted, the tenant configuration will be used.

To learn more about overriding email templates, see the Application Specific Email Templates guide.

codeStringrequired

A valid Multi-Factor verification code. This value should be provided by the User to verify they are able to produce codes.

methodStringrequired

The User's delivery method for verification codes. You can enable multiple methods with multiple requests. The method must be enabled in the Tenant configuration.

The possible values are:

  • authenticator
  • email
  • sms
emailStringoptional

The email address used for this method of authentication.

If method is email, this field is required.

mobilePhoneStringoptional

The mobile phone number used for this method of authentication.

If method is sms, this field is required.

nameStringoptionalAvailable since 1.68.0

The display name for this multi-factor method.

The maximum length is 256 characters.

secretStringoptional

A base64 encoded secret.

You may optionally use the secret value returned by the Two-Factor Secret API instead of generating this value yourself. This value is a secure random byte array that is Base-64 encoded.

If method is authenticator and you omit this field, then secretBase32Encoded is required.

secretBase32EncodedStringoptional

A base32 encoded secret.

You may optionally use the secretBase32Encoded value returned by the Two-Factor Secret API instead of generating this value yourself. This value is a secure random byte array that is Base-32 encoded.

If method is authenticator and you omit this field, then secret is required.

twoFactorIdStringoptionalAvailable since 1.42.0

A two-factor identifier that was returned on the Login API when the user is required to configure a two-factor method. When provided, the API response will include a two-factor code that can be used to complete a two-factor login request.

Example Request JSON Enabling a TOTP Factor

{
  "code": "435612",
  "method": "authenticator",
  "name": "Work authenticator",
  "secret": "8MJJfCY4ERBtotvenSc3",
  "twoFactorId": "a6yRXP9-FF0sqD86L_1n_zRp6iAS_aXuuhQM8OL_nIA"
}

Example Request JSON Enabling an Email Factor

{
  "code": "435612",
  "email": "richard@piedpiper.com",
  "method": "email",
  "name": "Work email"
}
JWT Authentication
Enable Multi-Factor Authentication Using a JWT
POST/api/user/two-factor

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. This parameter is optional, and when provided it will cause application specific configuration to be used when available.

For example, to use an application specific email template to notify the user when multi-factor has been enabled, this parameter will be required. When this parameter is omitted, the tenant configuration will be used.

To learn more about overriding email templates, see the Application Specific Email Templates guide.

codeStringrequired

A valid Multi-Factor verification code. This value should be provided by the User to verify they are able to produce codes.

methodStringrequired

The User's delivery method for verification codes. You can enable multiple methods with multiple requests. The method must be enabled in the Tenant configuration.

The possible values are:

  • authenticator
  • email
  • sms
emailStringoptional

The email address used for this method of authentication.

If method is email, this field is required.

mobilePhoneStringoptional

The mobile phone number used for this method of authentication.

If method is sms, this field is required.

nameStringoptionalAvailable since 1.68.0

The display name for this multi-factor method.

The maximum length is 256 characters.

secretStringoptional

A base64 encoded secret.

You may optionally use the secret value returned by the Two-Factor Secret API instead of generating this value yourself. This value is a secure random byte array that is Base-64 encoded.

If method is authenticator and you omit this field, then secretBase32Encoded is required.

secretBase32EncodedStringoptional

A base32 encoded secret.

You may optionally use the secretBase32Encoded value returned by the Two-Factor Secret API instead of generating this value yourself. This value is a secure random byte array that is Base-32 encoded.

If method is authenticator and you omit this field, then secret is required.

twoFactorIdStringoptionalAvailable since 1.42.0

A two-factor identifier that was returned on the Login API when the user is required to configure a two-factor method. When provided, the API response will include a two-factor code that can be used to complete a two-factor login request.

Example Request JSON Enabling a TOTP Factor

{
  "code": "435612",
  "method": "authenticator",
  "name": "Work authenticator",
  "secret": "8MJJfCY4ERBtotvenSc3",
  "twoFactorId": "a6yRXP9-FF0sqD86L_1n_zRp6iAS_aXuuhQM8OL_nIA"
}

Example Request JSON Enabling an Email Factor

{
  "code": "435612",
  "email": "richard@piedpiper.com",
  "method": "email",
  "name": "Work email"
}

Response#

Response Codes

CodeDescription
200The request was successful. Multi-Factor has been enabled for the User.
400The 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.
401You 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.
404The User does not exist. The response will be empty.
421The code request parameter is not valid. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

This response body is returned only when the first method is added. After that, this call does not return a JSON response body.

codeStringAvailable since 1.42.0

Code generated to complete a Two-Factor login if twoFactorId is provided on the request.

recoveryCodesArray

A list of recovery codes. These may be used in place of a code provided by an MFA factor. They are single use.

If a recovery code is used in a disable request, all MFA methods are removed. If, after that, a Multi-Factor method is added, a new set of recovery codes will be generated.

Since 1.68.0, these codes are the only time they are available in plaintext — store them securely and provide them to the user immediately. They are hashed at rest and cannot be retrieved afterward.

Example Response JSON with recovery codes.

{
  "code": "752185",
  "recoveryCodes": [
    "QJD73-L6GR5",
    "R7RJH-GB7H3",
    "JJ5YZ-KS4C3",
    "CRDHP-7L355",
    "928QS-P9HMJ",
    "8VLFT-Z2WMM",
    "PQZX9-YV5VR",
    "TK9TB-7BT6H",
    "6QYPL-ZPQJV",
    "VJ35W-98RW4"
  ]
}

Disable Multi-Factor#

This API is used to disable Multi-Factor authentication for a single User. To use this API the User must provide a valid Multi-Factor verification code or recovery code.

If using message based delivery, you may Send a Multi-Factor Code When Disabling MFA to deliver a code to the User. The User will then provide this code as input.

If a recovery code is provided, all methods will be removed.

Request#

API Key Authentication
Disable a single multi-factor method by User Id
DELETE/api/user/two-factor/{userId}?code={code}&methodId={methodId}

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

applicationIdUUIDoptionalAvailable since 1.44.0

An application Id. This parameter is optional, and when provided it will cause application specific configuration to be used when available.

For example, to use an application specific email template to notify the user when multi-factor has been enabled, this parameter will be required. When this parameter is omitted, the tenant configuration will be used.

To learn more about overriding email templates, see the Application Specific Email Templates guide.

codeStringrequired

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodIdStringrequired

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

API Key Authentication
Disable a single multi-factor method by User Id
DELETE/api/user/two-factor/{userId}

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. This parameter is optional, and when provided it will cause application specific configuration to be used when available.

For example, to use an application specific email template to notify the user when multi-factor has been enabled, this parameter will be required. When this parameter is omitted, the tenant configuration will be used.

To learn more about overriding email templates, see the Application Specific Email Templates guide.

codeStringrequired

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodIdStringrequired

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

Example Request JSON

{
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "code": "549457",
  "methodId": "email"
}
JWT Authentication
Disable a single multi-factor method using a JWT
DELETE/api/user/two-factor

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. This parameter is optional, and when provided it will cause application specific configuration to be used when available.

For example, to use an application specific email template to notify the user when multi-factor has been enabled, this parameter will be required. When this parameter is omitted, the tenant configuration will be used.

To learn more about overriding email templates, see the Application Specific Email Templates guide.

codeStringrequired

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodIdStringrequired

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

Example Request JSON

{
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "code": "549457",
  "methodId": "email"
}
JWT Authentication
Disable a single multi-factor method using a JWT
DELETE/api/user/two-factor?code={code}&methodId={methodId}

Request Parameters#

applicationIdUUIDoptionalAvailable since 1.44.0

An application Id. This parameter is optional, and when provided it will cause application specific configuration to be used when available.

For example, to use an application specific email template to notify the user when multi-factor has been enabled, this parameter will be required. When this parameter is omitted, the tenant configuration will be used.

To learn more about overriding email templates, see the Application Specific Email Templates guide.

codeStringrequired

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodIdStringrequired

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

Response#

Response Codes

CodeDescription
200The request was successful. Multi-Factor has been disabled for the User.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401You 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.
404The User does not exist. The response will be empty.
421The code request parameter is not valid. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Update Multi-Factor Method#

This API updates the display name of a single configured multi-factor method for a User.

This operation only updates the method display name. It does not modify the MFA method type or delivery configuration.

Request#

API Key Authentication
Update a single multi-factor method by User Id
PUT/api/user/two-factor/{userId}?methodId={methodId}
Available since 1.68.0

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

userIdUUIDrequired

The Id of the User for whom to update Multi-Factor authentication.

methodIdStringrequired

The Id of the multi-factor method to update.

Request Body#

nameStringoptional

The display name for the configured multi-factor method.

The maximum length is 256 characters.

If omitted, the method name will be cleared.

Example Request JSON

{
  "name": "Work phone"
}

Response#

Response Codes

CodeDescription
200The request was successful. The response will be empty.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401You 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.
404The User does not exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Generate a Secret#

This API is used to generate a new multi-factor secret for use when enabling multi-factor authentication for a User. This is provided as a helper to assist you in enabling multi-factor authentication.

If this secret will be used with a QR code to allow the User to scan the value, use the Base32 encoded value returned in the response.

Request#

API Key Authentication
Generate a multi-factor Secret
GET/api/two-factor/secret
JWT Authentication
Generate a multi-factor Secret
GET/api/two-factor/secret

Response#

The response for this API contains a Multi-Factor secret suitable for an authenticator like Google Authenticator.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

secretString

A Base64 encoded secret that may be used to enable Multi-Factor authentication.

secretBase32EncodedString

A Base32 encoded form of the provided secret. This is useful if you need to provide a QR code to the User to enable Multi-Factor authentication.

Example Response JSON

{
  "secret": "8MJJfCY4ERBtotvenSc3",
  "secretBase32Encoded": "HBGUUSTGINMTIRKSIJ2G65DWMVXFGYZT"
}

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#

API Key Authentication
Start multi-factor authentication
POST/api/two-factor/start

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
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
404The User does not exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The 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"
}

Retrieve Multi-Factor Status#

Retrieves a user's multi-factor status. This is helpful to understand if a user has multi-factor authentication enabled, and if the user will be required to perform a multi-factor challenge during the next login request.

This API may also be used to identify if an existing multi-factor trust value obtained during a multi-factor login is expired, or valid for a specific application when configured to restrict multi-factor trust.

Since version 1.62.0, prefer the POST method for this endpoint, which provides more information to MFA requirement lambda functions.

Request#

API Key Authentication
Retrieve multi-factor status
GET/api/two-factor/status/{twoFactorTrustId}

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

applicationIdStringoptional

A unique application Id. When Application multi-factor configuration is enabled, providing this parameter will ensure the returned status applies to the expected result when attempting to login into this application.

twoFactorTrustIdStringoptional

The existing multi-factor trust obtained by completing a multi-factor login. This is the value that allows you to bypass multi-factor during the next login attempt.

userIdStringrequired

The unique Id of the user for which to retrieve multi-factor status.

API Key Authentication
Retrieve multi-factor status using request payload
POST/api/two-factor/status
Available since 1.62.0

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#

actionStringoptionalDefaults to login

The action the user is attempting to perform. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

Valid values are:

  • changePassword
  • login
  • stepUp
applicationIdStringoptional

A unique application Id. When Application multi-factor configuration is enabled, providing this parameter will ensure the returned status applies to the expected result when attempting to login into this application.

accessTokenStringoptional

An access token (not an Id token) returned by FusionAuth as the result of a successful authentication. The encoded access token will be available in context.accessToken in an MFA requirement lambda function. See the MFA requirement lambda documentation. This must be a valid token that was issued and signed by FusionAuth.

twoFactorTrustIdStringoptional

The existing multi-factor trust obtained by completing a multi-factor login. This is the value that allows you to bypass multi-factor during the next login attempt.

userIdStringrequired

The unique Id of the user for which to retrieve multi-factor status.

Example POST Request JSON

{
  "action": "stepUp",
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "eventInfo": {
    "data": {
      "page": "/account/bank-accounts"
    },
    "ipAddress": "127.0.0.1"
  },
  "userId": "429797ba-37d7-4bbe-8748-58fb812448ff"
}

Response#

Response Codes

CodeDescription
200The user does not have multi-factor enabled, a challenge is not required, or the provided trust is still valid for the next login.
242The user has multi-factor authentication enabled. Since version 1.42.0, this status code is also returned when multi-factor authentication is required. The user will be required to complete a multi-factor challenge during the next login attempt. This status code can also be used to determine whether step up is required.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

trustsArray

An array of one or more trust configurations.

twoFactorTrustIdString

The value provided in the twoFactorTrustId on the request.

Example Response JSON

{
  "trusts": [
    {
      "applicationId": "975c7d21-f4b7-4a16-bbb9-a7826045f7e2",
      "expiration": 1660946705239,
      "expired": false,
      "startInstant": 1660860305239
    }
  ],
  "twoFactorTrustId": "XOgai4Ro68xfGiex0ngXiJ2bbhduM4Pm7h3lvF0xibQ"
}

Send a Multi-Factor Code During Login or Step Up#

This operation allows you to send a message with a code to finish a Multi-Factor flow, and requires an existing twoFactorId. No API key is required.

This should only be used if you want FusionAuth to send the code. Do not use this if you are sending a code out of band or are using a TOTP based authentication method.

You can use this to re-send a code with the same or a different method. Using this API will invalidate all other codes previously associated with the provided twoFactorId.

Sending a code invalidates all previous codes for the provided twoFactorId.

Request#

No Authentication Required
Send a multi-factor code to complete Multi-Factor Login
POST/api/two-factor/send/{twoFactorId}

Request Parameters#

twoFactorIdStringrequired

The twoFactorId returned by the Login API or the Start multi-factor request.

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#

messageTypeStringoptionalDefaults to SMSAvailable since 1.65.0

The message type used when sending a code for a phone-based MFA method.

This value is only used when the selected MFA method is sms.

Valid values are:

  • SMS
  • Voice
methodIdStringrequired

The Id of the MFA method to be used.

Example Request JSON

{
  "messageType": "Voice",
  "methodId": "KLRT"
}

Response#

This API does not return a JSON response body.

Response Codes
CodeDescription
200The request was successful.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Send a Multi-Factor Code When Enabling MFA#

You are enabling MFA for a user. You must provide an API key or a valid JWT for the User you are modifying. This should only be used if you want FusionAuth to send the code. Do not use this if you are using a TOTP based authentication method.

Request#

API Key Authentication
Send a Multi-Factor code to an existing User by Id
POST/api/two-factor/send

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#

applicationIdUUIDoptionalAvailable since 1.46.0

An optional Application Id. When this value is provided, it will be used to resolve an application-specific email or message template and make application available as a template variable.

If not provided, only the tenant configuration will be used when resolving templates, and application will not be available as a template variable.

emailStringoptional

The email to which send Multi-Factor codes. If the method is equal to email, this is required.

messageTypeStringoptionalDefaults to SMSAvailable since 1.65.0

The message type used when sending a code for a phone-based MFA method.

This value is only used when method is equal to sms.

Valid values are:

  • SMS
  • Voice
methodStringrequired

The type of the MFA method which will be added. The value provided here must be allowed in the Tenant MFA configuration as well.

Valid values are:

  • email
  • sms
mobilePhoneStringoptional

The mobile phone to which send Multi-Factor codes. If the method is equal to sms, this is required.

userIdUUIDrequired

The User Id.

Example Request JSON

{
  "messageType": "Voice",
  "method": "sms",
  "mobilePhone": "+13035551212",
  "userId": "c075e472-a732-47d6-865a-d385a5fcb525"
}
JWT Authentication
Send a Multi-Factor code to an authenticated User using a JWT
POST/api/two-factor/send

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#

applicationIdUUIDoptionalAvailable since 1.46.0

An optional Application Id. When this value is provided, it will be used to resolve an application-specific email or message template and make application available as a template variable.

If not provided, only the tenant configuration will be used when resolving templates, and application will not be available as a template variable.

emailStringoptional

The email to which send Multi-Factor codes. If the method is equal to email, this is required.

messageTypeStringoptionalDefaults to SMSAvailable since 1.65.0

The message type used when sending a code for a phone-based MFA method.

This value is only used when method is equal to sms.

Valid values are:

  • SMS
  • Voice
methodStringrequired

The type of the MFA method which will be added. The value provided here must be allowed in the Tenant MFA configuration as well.

Valid values are:

  • email
  • sms
mobilePhoneStringoptional

The mobile phone to which send Multi-Factor codes. If the method is equal to sms, this is required.

Example Request JSON

{
  "messageType": "Voice",
  "method": "sms",
  "mobilePhone": "+13035551212"
}

Response#

This API does not return a JSON response body.

Response Codes
CodeDescription
200The request was successful.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Send a Multi-Factor Code When Disabling MFA#

You are disabling MFA for a user. You must provide an API key or a valid JWT for the User you are modifying. This should only be used if you want FusionAuth to send the code. Do not use this if you are using a TOTP based authentication method.

Request#

API Key Authentication
Send a Multi-Factor code to an existing User by Id
POST/api/two-factor/send

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#

applicationIdUUIDoptionalAvailable since 1.46.0

An optional Application Id. When this value is provided, it will be used to resolve an application-specific email or message template and make application available as a template variable.

If not provided, only the tenant configuration will be used when resolving templates, and application will not be available as a template variable.

messageTypeStringoptionalDefaults to SMSAvailable since 1.65.0

The message type used when sending a code for a phone-based MFA method.

This value is only used when the method identified by methodId is an sms method.

Valid values are:

  • SMS
  • Voice
methodIdStringrequired

The Id of the MFA method which will be removed.

userIdUUIDrequired

The User Id of the User to send a Multi-Factor verification code. This User is expected to already have Multi-Factor enabled.

Example Request JSON

{
  "messageType": "Voice",
  "methodId": "RLRT",
  "userId": "c075e472-a732-47d6-865a-d385a5fcb525"
}
JWT Authentication
Send a Multi-Factor code to an authenticated User using a JWT
POST/api/two-factor/send

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#

applicationIdUUIDoptionalAvailable since 1.46.0

An optional Application Id. When this value is provided, it will be used to resolve an application-specific email or message template and make application available as a template variable.

If not provided, only the tenant configuration will be used when resolving templates, and application will not be available as a template variable.

messageTypeStringoptionalDefaults to SMSAvailable since 1.65.0

The message type used when sending a code for a phone-based MFA method.

This value is only used when the method identified by methodId is an sms method.

Valid values are:

  • SMS
  • Voice
methodIdStringrequired

The Id of the MFA method which will be removed.

Example Request JSON

{
  "messageType": "Voice",
  "methodId": "RLRT"
}

Response#

This API does not return a JSON response body.

Response Codes
CodeDescription
200The request was successful.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Generate Recovery Codes#

This API is used to generate a list of Recovery Codes. When creating new codes, any existing Recovery Codes will be cleared and the new set will become the current values.

Request#

API Key Authentication
Create Recovery Codes
POST/api/user/two-factor/recovery-code/{userId}

Request Parameters#

userIdUUIDrequired

The unique Id of the user to assign the generated Recovery Codes to.

Response#

The response for this API contains an array of Recovery Codes that were created. In both standard and FIPS modes, 10 codes are returned. In standard mode, codes use the format XXXXX-XXXXX. In FIPS mode, codes use the format XXXXXXX-XXXXXXX.

The returned codes are the only time they are available in plaintext — they are hashed at rest and cannot be retrieved afterward. Store them securely and provide them to the user immediately. Since 1.68.0.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

recoveryCodesArray<String>

The array of Recovery Codes.

Example Response JSON

{
  "code": "752185",
  "recoveryCodes": [
    "QJD73-L6GR5",
    "R7RJH-GB7H3",
    "JJ5YZ-KS4C3",
    "CRDHP-7L355",
    "928QS-P9HMJ",
    "8VLFT-Z2WMM",
    "PQZX9-YV5VR",
    "TK9TB-7BT6H",
    "6QYPL-ZPQJV",
    "VJ35W-98RW4"
  ]
}

Retrieve Recovery Codes#

This API is used to retrieve Recovery Codes for a User.

Request#

API Key Authentication
Retrieve Recovery Codes (deprecated)
GET/api/user/two-factor/recovery-code/{userId}
Deprecated since 1.64.0
This endpoint is deprecated. To provide access to a user's recovery codes, generate new recovery codes and deliver those

As of 1.68.0, this endpoint always returns an empty list. Recovery codes are now hashed at rest and cannot be retrieved in plaintext. To provide a user with recovery codes, generate a new set.

Request Parameters#

userIdUUIDrequired

The Id of the User to retrieve Recovery Codes for.

Response#

The response for this API contains the remaining Recovery Codes that are assigned to the User. Each time one is used it is removed, so this response will contain between 0 and 10 codes. Prior to 1.68.0, this returned remaining codes. As of 1.68.0, this always returns an empty list.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

recoveryCodesArray<String>

The array of Recovery Codes.

Example Response JSON

{
  "code": "752185",
  "recoveryCodes": [
    "QJD73-L6GR5",
    "R7RJH-GB7H3",
    "JJ5YZ-KS4C3",
    "CRDHP-7L355",
    "928QS-P9HMJ",
    "8VLFT-Z2WMM",
    "PQZX9-YV5VR",
    "TK9TB-7BT6H",
    "6QYPL-ZPQJV",
    "VJ35W-98RW4"
  ]
}