/Docs

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}
OpenAPI Spec

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