Logo / Docs

Multi-Factor

FusionAuth Reactor logo

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

This API underwent breaking changes in version 1.26.

If you are using a version of FusionAuth prior to 1.26.0, you should upgrade. 😎   But if you cannot - here is the doc you are looking for: old Two Factor doc.

Overview

This API allows you to manage multi-factor authentication (MFA) for users.

You might be wondering, what is the difference between multi-factor authentication and two factor authentication.

A factor is anything a user has, is, or can provide which can uniquely identify the user. A password which historically has been used to identify and authenticate a user is flawed in that it is likely not globally unique, and it can be assumed that eventually it will be known by more than one person. Additional factors can be used to authenticate a user to mitigate the limitations of the traditional password.

When a system can support more than one method of authentication, it is considered to support multiple factors, or MFA. In addition to password authentication, FusionAuth supports a time based one time password, also referred to as TOTP, and an SMS or Email based one time use code. This means FusionAuth supports multiple factor authentication, or MFA.

Two-factor authentication, or 2FA more specifically refers to the practice of requiring two factors of authentication to complete a login request. In practice, this usually means requiring a password, and one additional factor of authentication.

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

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

applicationIdUUID

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
emailString

The email address used for this method of authentication.

If method is email, this field is required.

mobilePhoneString

The mobile phone number used for this method of authentication.

If method is sms, this field is required.

secretString

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.

secretBase32EncodedString

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.

twoFactorIdStringAvailable 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",
  "secret": "8MJJfCY4ERBtotvenSc3",
  "twoFactorId": "a6yRXP9-FF0sqD86L_1n_zRp6iAS_aXuuhQM8OL_nIA"
}

Example Request JSON Enabling an Email Factor

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

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdUUID

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
emailString

The email address used for this method of authentication.

If method is email, this field is required.

mobilePhoneString

The mobile phone number used for this method of authentication.

If method is sms, this field is required.

secretString

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.

secretBase32EncodedString

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.

twoFactorIdStringAvailable 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",
  "secret": "8MJJfCY4ERBtotvenSc3",
  "twoFactorId": "a6yRXP9-FF0sqD86L_1n_zRp6iAS_aXuuhQM8OL_nIA"
}

Example Request JSON Enabling an Email Factor

{
  "code": "435612",
  "email": "richard@piedpiper.com",
  "method": "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.

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

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

applicationIdUUIDAvailable 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-TenantIdString

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

applicationIdUUID

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

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

applicationIdUUID

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

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

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
Code Description
200 The request was successful. The response will contain a JSON body.
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.
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

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

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

applicationIdUUID

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

codeString

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 email or the username 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.

Prior to version 1.33.0, this field was always required because the userId was not available as an option.

stateObject

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

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

userIdUUIDAvailable 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].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",
      "authenticator": {
        "algorithm": "HmacSHA1",
        "codeLength": 6,
        "timeStep": 30
      }
    },
    {
      "id": "KLRT",
      "method": "email",
      "email": "richard@piedpiper.com",
      "lastUsed": true
    },
    {
      "id": "K8RT",
      "method": "email",
      "email": "dinesh@piedpiper.com"
    },
    {
      "id": "87KW",
      "method": "sms",
      "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.

Request

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

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdString

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.

twoFactorTrustIdString

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.

Response

.Response Codes

CodeDescription
200The user does not have multi-factor enabled, 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 two factor authentication is required. The user will be required to complete a two-factor challenge during the next login attempt.
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-TenantIdString

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

methodIdStringrequired

The Id of the MFA method to be used.

Example Request JSON

{
  "methodId": "KLRT"
}

Response

This API does not return a JSON response body.

Response Codes
Code Description
200 The request was successful.
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.
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.

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

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

applicationIdUUIDAvailable since 1.46.0

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

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

emailString

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

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
mobilePhoneString

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

{
  "email": "richard@piedpiper.com",
  "method": "email",
  "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-TenantIdString

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

applicationIdUUIDAvailable since 1.46.0

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

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

emailString

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

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
mobilePhoneString

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

Example Request JSON

{
  "email": "richard@piedpiper.com",
  "method": "email"
}

Response

This API does not return a JSON response body.

Response Codes
Code Description
200 The request was successful.
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.
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.

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

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

applicationIdUUIDAvailable since 1.46.0

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

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

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

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

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

applicationIdUUIDAvailable since 1.46.0

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

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

methodIdStringrequired

The Id of the MFA method which will be removed.

Example Request JSON

{
  "methodId": "RLRT"
}

Response

This API does not return a JSON response body.

Response Codes
Code Description
200 The request was successful.
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.
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.

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 size 10 of Recovery Codes that were created.

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.
500 There 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
GET /api/user/two-factor/recovery-code/{userId}

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.

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.
500 There 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"
  ]
}