> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Start Multi-Factor API documentation for the FusionAuth Start Multi-Factor API. # 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](https://fusionauth.io/docs/apis/two-factor/send-a-multi-factor-code-during-login-or-step-up.md) 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](https://fusionauth.io/docs/apis/two-factor/enable-multi-factor.md) 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](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Start multi-factor authentication POST/api/two-factor/start OpenAPI Spec #### 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. If this is not provided and there are multiple tenants, the **X-FusionAuth-TenantId** header is required. `code`Stringoptional 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. `loginId`String 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. `loginIdTypes`ArrayoptionalDefaults 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` note 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. `state`Objectoptional Additional data to be passed through this Multi-Factor request. After successful login, the **state** field in the response will contain this data. `trustChallenge`StringoptionalAvailable 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. `userId`UUIDoptionalAvailable 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* ```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](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. | | 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 `code`String A valid Multi-Factor verification code. `methods`Array A list of configured authentication methods. This field will be omitted if none have been configured. `methods[x].id`String The identifier for this method. `methods[x].name`StringoptionalAvailable since 1.68.0 The display name for this method. `methods[x].lastUsed`Boolean `true` if this method was used most recently. `methods[x].method`String 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].authenticator`Object An object with additional configuration for TOTP authentication methods. Only present if **methods`[x]`.method** is `authenticator`. `methods[x].authenticator.algorithm`String 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.codeLength`Integer The length of code generated by the TOTP. With the current implementation, this will always be 6. `methods[x].authenticator.timeStep`Integer The time-step size in seconds. With the current implementation, this will always be 30. `methods[x].email`String The value of the email address for this method. Only present if **methods`[x]`.method** is `email`. `methods[x].mobilePhone`String The value of the mobile phone for this method. Only present if **methods`[x]`.method** is `sms`. `twoFactorId`String 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* ```json { "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* ```json { "code": "123456", "twoFactorId": "DvnAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs" } ```