> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Enable Multi-Factor

API documentation for the FusionAuth Enable Multi-Factor API.

# 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](https://fusionauth.io/docs/apis/two-factor/send-a-multi-factor-code-when-enabling-mfa.md) to deliver a code to the User. The User will then provide this code as input.

## Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Enable Multi-Factor Authentication by User Id

POST/api/user/two-factor/{userId}

OpenAPI Spec

### Request Parameters

`userId`UUIDrequired

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

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`applicationId`UUIDoptional

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](https://fusionauth.io/docs/customize/email-and-messages/configuring-application-specific-email-templates.md) guide.

`code`Stringrequired

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

`method`Stringrequired

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`

`email`Stringoptional

The email address used for this method of authentication.

If **method** is `email`, this field is required.

`mobilePhone`Stringoptional

The mobile phone number used for this method of authentication.

If **method** is `sms`, this field is required.

`name`StringoptionalAvailable since 1.68.0

The display name for this multi-factor method.

The maximum length is 256 characters.

`secret`Stringoptional

A base64 encoded secret.

You may optionally use the **secret** value returned by the [Two-Factor Secret](https://fusionauth.io/docs/apis/two-factor/generate-a-secret.md) 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.

`secretBase32Encoded`Stringoptional

A base32 encoded secret.

You may optionally use the **secretBase32Encoded** value returned by the [Two-Factor Secret](https://fusionauth.io/docs/apis/two-factor/generate-a-secret.md) 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.

`twoFactorId`StringoptionalAvailable 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*

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

*Example Request JSON Enabling an Email Factor*

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

[!JWT Authentication](https://fusionauth.io/docs/apis/authentication.md#jwt-authentication)

Enable Multi-Factor Authentication Using a JWT

POST/api/user/two-factor

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`applicationId`UUIDoptional

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](https://fusionauth.io/docs/customize/email-and-messages/configuring-application-specific-email-templates.md) guide.

`code`Stringrequired

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

`method`Stringrequired

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`

`email`Stringoptional

The email address used for this method of authentication.

If **method** is `email`, this field is required.

`mobilePhone`Stringoptional

The mobile phone number used for this method of authentication.

If **method** is `sms`, this field is required.

`name`StringoptionalAvailable since 1.68.0

The display name for this multi-factor method.

The maximum length is 256 characters.

`secret`Stringoptional

A base64 encoded secret.

You may optionally use the **secret** value returned by the [Two-Factor Secret](https://fusionauth.io/docs/apis/two-factor/generate-a-secret.md) 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.

`secretBase32Encoded`Stringoptional

A base32 encoded secret.

You may optionally use the **secretBase32Encoded** value returned by the [Two-Factor Secret](https://fusionauth.io/docs/apis/two-factor/generate-a-secret.md) 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.

`twoFactorId`StringoptionalAvailable 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*

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

*Example Request JSON Enabling an Email Factor*

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

## Response

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. Multi-Factor has been enabled for the User. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The User does not exist. The response will be empty. |
| 421 | The `code` request parameter is not valid. 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

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

`code`StringAvailable since 1.42.0

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

`recoveryCodes`Array

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

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