Multi-Factor/Two Factor APIs

Request Parameters

userId [UUID] Required

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

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [UUID] Optional

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.

code [String] Required

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

method [String] Required

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 [String] Optional

The email address used for this method of authentication.

If method is email, this field is required.

mobilePhone [String] Optional

The mobile phone number used for this method of authentication.

If method is sms, this field is required.

secret [String] Optional

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.

secretBase32Encoded [String] Optional

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.

twoFactorId [String] Optional Available 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.

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

{
  "code": "435612",
  "email": "richard@piedpiper.com",
  "method": "email"
}

Enable Multi-Factor Authentication Using a JWT

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [UUID] Optional

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.

code [String] Required

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

method [String] Required

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 [String] Optional

The email address used for this method of authentication.

If method is email, this field is required.

mobilePhone [String] Optional

The mobile phone number used for this method of authentication.

If method is sms, this field is required.

secret [String] Optional

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.

secretBase32Encoded [String] Optional

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.

twoFactorId [String] Optional Available 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.

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

{
  "code": "435612",
  "email": "richard@piedpiper.com",
  "method": "email"
}

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 [String] Available 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.

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

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [UUID] Optional Available since 1.44.0

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.

code [String] Required

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodId [String] Required

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

Disable a single multi-factor method by User Id

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [UUID] Optional

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.

code [String] Required

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodId [String] Required

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

{
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "code": "549457",
  "methodId": "email"
}

Disable a single multi-factor method using a JWT

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [UUID] Optional

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.

code [String] Required

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodId [String] Required

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

{
  "applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
  "code": "549457",
  "methodId": "email"
}

Disable a single multi-factor method using a JWT

Request Parameters

applicationId [UUID] Optional Available since 1.44.0

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.

code [String] Required

A valid multi-factor verification code. The User will obtain this code using an existing multi-factor method which may include an authenticator (TOTP) app, sms or email. This procedure is the same as if the user was completing a multi-factor challenge during login.

This may also be a recovery code. If one is provided, all methods are removed. If, after that, a multi-factor method is added, a new set of recovery codes will be generated.

methodId [String] Required

The Id of the multi-factor method to be disabled.

If a recovery code is provided, this can be any valid method Id.

Response Body

secret [String]

A Base64 encoded secret that may be used to enable Multi-Factor authentication.

secretBase32Encoded [String]

A Base32 encoded form of the provided secret. This is useful if you need to provide a QR code to the User to enable Multi-Factor authentication.

{
  "secret": "8MJJfCY4ERBtotvenSc3",
  "secretBase32Encoded": "HBGUUSTGINMTIRKSIJ2G65DWMVXFGYZT"
}

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [UUID] Optional

An application Id. If this is not provided and there are multiple tenants, the X-FusionAuth-TenantId header is required.

code [String] Optional

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] Optional

The email or the username 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.

Prior to version 1.33.0, this field was always required because the userId was not available as an option.

state [Object] Optional

Additional data to be passed through this Multi-Factor request. After successful login, the state field in the response will contain this data.

trustChallenge [String] Optional Available 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 [UUID] Optionally Required Available 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.

{
  "loginId": "richard@piedpiper.com",
  "applicationId": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
  "code": "123456",
  "state": {
    "redirect_uri": "https://fusionauth.io"
  }
}

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

{
  "code": "123456",
  "methods": [
    {
      "id": "BD5R",
      "method": "authenticator",
      "authenticator": {
        "algorithm": "HmacSHA1",
        "codeLength": 6,
        "timeStep": 30
      }
    },
    {
      "id": "KLRT",
      "method": "email",
      "email": "richard@piedpiper.com",
      "lastUsed": true
    },
    {
      "id": "K8RT",
      "method": "email",
      "email": "dinesh@piedpiper.com"
    },
    {
      "id": "87KW",
      "method": "sms",
      "mobilePhone": "+13035551212"
    }
  ],
  "twoFactorId": "DvnAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}

{
  "code": "123456",
  "twoFactorId": "DvnAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}

Request Parameters

twoFactorId [String] Required

The twoFactorId returned by the Login API or the Start multi-factor request.

Request Headers

X-FusionAuth-TenantId [String] Optional

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

methodId [String] Required

The Id of the MFA method to be used.

{
  "methodId": "KLRT"
}

Request Headers

X-FusionAuth-TenantId [String] Optional

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

applicationId [String] Optional

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 [String] Optional

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 [String] Required

The unique Id of the user for which to retrieve multi-factor status.

Response Body

trusts [Array]

An array of one or more trust configurations.

twoFactorTrustId [String]

The value provided in the twoFactorTrustId on the request.

{
  "trusts": [
    {
      "applicationId": "975c7d21-f4b7-4a16-bbb9-a7826045f7e2",
      "expiration": 1660946705239,
      "expired": false,
      "startInstant": 1660860305239
    }
  ],
  "twoFactorTrustId": "XOgai4Ro68xfGiex0ngXiJ2bbhduM4Pm7h3lvF0xibQ"
}

Request Headers

X-FusionAuth-TenantId [String] Optional

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

email [String] Optional

The email to which send Multi-Factor codes. If the method is equal to email, this is required.

method [String] Required

The type of the MFA method which will be added. The value provided here must be allowed in the Tenant MFA configuration as well.

Valid values are:

• email

• sms

mobilePhone [String] Optional

The mobile phone to which send Multi-Factor codes. If the method is equal to sms, this is required.

userId [UUID] Required

The User Id.

{
  "email": "richard@piedpiper.com",
  "method": "email",
  "userId": "c075e472-a732-47d6-865a-d385a5fcb525"
}

Send a Multi-Factor code to an authenticated User using a JWT

Request Headers

X-FusionAuth-TenantId [String] Optional

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

email [String] Optional

The email to which send Multi-Factor codes. If the method is equal to email, this is required.

method [String] Required

The type of the MFA method which will be added. The value provided here must be allowed in the Tenant MFA configuration as well.

Valid values are:

• email

• sms

mobilePhone [String] Optional

The mobile phone to which send Multi-Factor codes. If the method is equal to sms, this is required.

{
  "email": "richard@piedpiper.com",
  "method": "email"
}

Request Headers

X-FusionAuth-TenantId [String] Optional

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

methodId [String] Required

The Id of the MFA method which will be removed.

userId [UUID] Required

The User Id of the User to send a Multi-Factor verification code. This User is expected to already have Multi-Factor enabled.

{
  "methodId": "RLRT",
  "userId": "c075e472-a732-47d6-865a-d385a5fcb525"
}

Send a Multi-Factor code to an authenticated User using a JWT

Request Headers

X-FusionAuth-TenantId [String] Optional

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

methodId [String] Required

The Id of the MFA method which will be removed.

{
  "methodId": "RLRT"
}

Request Parameters

userId [UUID] Required

The unique Id of the user to assign the generated Recovery Codes to.

Response Body

recoveryCodes [Array<String>]

The array of 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"
  ]
}

Request Parameters

userId [UUID] Required

The Id of the User to retrieve Recovery Codes for.

Response Body

recoveryCodes [Array<String>]

The array of 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"
  ]
}