/Docs

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.

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
Retrieve multi-factor status
GET/api/two-factor/status/{twoFactorTrustId}
OpenAPI Spec

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 Parameters#

applicationIdStringoptional

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.

twoFactorTrustIdStringoptional

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.

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

actionStringoptionalDefaults 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
applicationIdStringoptional

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.

accessTokenStringoptional

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 documentation. This must be a valid token that was issued and signed by FusionAuth.

twoFactorTrustIdStringoptional

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.

Example POST Request 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

CodeDescription
200The user does not have multi-factor enabled, a challenge is not required, 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 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.
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"
}