> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Retrieve Multi-Factor Status API documentation for the FusionAuth Retrieve Multi-Factor Status API. # 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. note 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](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Retrieve multi-factor status GET/api/two-factor/status/{twoFactorTrustId} 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 Parameters `applicationId`Stringoptional 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. `twoFactorTrustId`Stringoptional 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. `userId`Stringrequired The unique Id of the user for which to retrieve multi-factor status. [!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Retrieve multi-factor status using request payload POST/api/two-factor/status OpenAPI Spec Available since 1.62.0 #### 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 `action`StringoptionalDefaults 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` `applicationId`Stringoptional 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. `accessToken`Stringoptional 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](https://fusionauth.io/docs/extend/code/lambdas/mfa-requirement.md) documentation. This must be a valid token that was issued and signed by FusionAuth. `twoFactorTrustId`Stringoptional 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. `userId`Stringrequired The unique Id of the user for which to retrieve multi-factor status. *Example POST Request JSON* ```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 | Code | Description | | --- | --- | | 200 | The user does not have multi-factor enabled, a challenge is not required, or the provided trust is still valid for the next login. | | 242 | The 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. | | 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. | | 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). | | 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 `trusts`Array An array of one or more trust configurations. `twoFactorTrustId`String The value provided in the **twoFactorTrustId** on the request. *Example Response JSON* ```json { "trusts": [ { "applicationId": "975c7d21-f4b7-4a16-bbb9-a7826045f7e2", "expiration": 1660946705239, "expired": false, "startInstant": 1660860305239 } ], "twoFactorTrustId": "XOgai4Ro68xfGiex0ngXiJ2bbhduM4Pm7h3lvF0xibQ" } ```