Multi-Factor/Two Factor APIs
Email and SMS multi—factor methods are only available in paid editions of FusionAuth. Please visit our pricing page to learn more about paid editions.
This API underwent breaking changes in version 1.26.
If you are using a version of FusionAuth prior to 1.26.0, you should upgrade. 😎 But if you cannot - here is the doc you are looking for: old Two Factor doc.
Overview
This API allows you to manage multi-factor authentication (MFA) for users.
You might be wondering, what is the difference between multi-factor authentication and two factor authentication.
A factor is anything a user has, is, or can provide which can uniquely identify the user. A password which historically has been used to identify and authenticate a user is flawed in that it is likely not globally unique, and it can be assumed that eventually it will be known by more than one person. Additional factors can be used to authenticate a user to mitigate the limitations of the traditional password.
When a system can support more than one method of authentication, it is considered to support multiple factors, or MFA. In addition to password authentication, FusionAuth supports a time based one time password, also referred to as TOTP, and an SMS or Email based one time use code. This means FusionAuth supports multiple factor authentication, or MFA.
Two-factor authentication, or 2FA more specifically refers to the practice of requiring two factors of authentication to complete a login request. In practice, this usually means requiring a password, and one additional factor of authentication.
Authentication
Some of these operations can use JWT authentication instead of API key authentication. In some cases, when you have a valid twoFactorId, neither a JWT nor an API key is required.
Learn more about JWT authentication and see examples here.
TOTP Implementation
Support for Authy, Google Authenticator and other time based one-time password solutions are not premium features and are included in the community edition.
While there is underlying support for different code lengths, algorithms and time steps, at the current time the system only allows for the following TOTP settings:
Configuration setting | Currently allowed value |
---|---|
|
|
|
|
|
|
Any attempt to change these configuration values will currently be ignored. If you need different configuration settings, please file a GitHub issue detailing your use case.
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 to deliver a code to the User. The User will then provide this code as input.
Request
Enable Multi-Factor Authentication by User Id
POST /api/user/two-factor/{userId}
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
POST /api/user/two-factor
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
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 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. |
404 |
The User does not exist. The response will be empty. |
421 |
The |
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 [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"
]
}
Disable Multi-Factor
This API is used to disable Multi-Factor authentication for a single User. To use this API the User must provide a valid Multi-Factor verification code or recovery code.
If using message based delivery, you may Send a Multi-Factor Code When Disabling MFA to deliver a code to the User. The User will then provide this code as input.
If a recovery code is provided, all methods will be removed.
Request
Disable a single multi-factor method by User Id
DELETE /api/user/two-factor/{userId}?code={code}&methodId={methodId}
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
DELETE /api/user/two-factor/{userId}
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
DELETE /api/user/two-factor
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
DELETE /api/user/two-factor?code={code}&methodId={methodId}
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
Code | Description |
---|---|
200 |
The request was successful. Multi-Factor has been disabled for the User. |
400 |
The request was invalid and/or malformed. The response will contain an Errors 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. |
404 |
The User does not exist. The response will be empty. |
421 |
The |
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. |
Generate a Secret
This API is used to generate a new multi-factor secret for use when enabling multi-factor authentication for a User. This is provided as a helper to assist you in enabling multi-factor authentication.
If this secret will be used with a QR code to allow the User to scan the value, use the Base32 encoded value returned in the response.
Request
Generate a multi-factor Secret
GET /api/two-factor/secret
Generate a multi-factor Secret
GET /api/two-factor/secret
Response
The response for this API contains a Multi-Factor secret suitable for an authenticator like Google Authenticator.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
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. |
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
- 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"
}
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 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 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
Start multi-factor authentication
POST /api/two-factor/start
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 thetrustToken
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
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 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. |
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]
.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 isauthenticator
. - 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 isemail
. - methods
[x]
.mobilePhone [String] -
The value of the mobile phone for this method. Only present if methods
[x]
.method issms
. - 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"
}
Send a Multi-Factor Code During Login or Step Up
This operation allows you to send a message with a code to finish a Multi-Factor flow, and requires an existing twoFactorId. No API key is required.
This should only be used if you want FusionAuth to send the code. Do not use this if you are sending a code out of band or are using a TOTP based authentication method.
You can use this to re-send a code with the same or a different method. Using this API will invalidate all other codes previously associated with the provided twoFactorId.
Sending a code invalidates all previous codes for the provided twoFactorId
.
Request
Send a multi-factor code to complete Multi-Factor Login
POST /api/two-factor/send/{twoFactorId}
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"
}
Response
This API does not return a JSON response body.
Code | Description |
---|---|
200 |
The request was successful. |
400 |
The request was invalid and/or malformed. The response will contain an Errors 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. |
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. |
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.
Request
GET /api/two-factor/status/{twoFactorTrustId}
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
Code | Description |
---|---|
200 |
The user does not have multi-factor enabled, or the provided trust is still valid for the next login. |
242 |
The user has multi-factor authentication enabled. Since version |
400 |
The request was invalid and/or malformed. The response will contain an Errors 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. |
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.
{
"trusts": [
{
"applicationId": "975c7d21-f4b7-4a16-bbb9-a7826045f7e2",
"expiration": 1660946705239,
"expired": false,
"startInstant": 1660860305239
}
],
"twoFactorTrustId": "XOgai4Ro68xfGiex0ngXiJ2bbhduM4Pm7h3lvF0xibQ"
}
Send a Multi-Factor Code When Enabling MFA
You are enabling MFA for a user. You must provide an API key or a valid JWT for the User you are modifying. This should only be used if you want FusionAuth to send the code. Do not use this if you are using a TOTP based authentication method.
Request
Send a Multi-Factor code to an existing User by Id
POST /api/two-factor/send
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
POST /api/two-factor/send
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"
}
Response
This API does not return a JSON response body.
Code | Description |
---|---|
200 |
The request was successful. |
400 |
The request was invalid and/or malformed. The response will contain an Errors 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. |
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. |
Send a Multi-Factor Code When Disabling MFA
You are disabling MFA for a user. You must provide an API key or a valid JWT for the User you are modifying. This should only be used if you want FusionAuth to send the code. Do not use this if you are using a TOTP based authentication method.
Request
Send a Multi-Factor code to an existing User by Id
POST /api/two-factor/send
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
POST /api/two-factor/send
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"
}
Response
This API does not return a JSON response body.
Code | Description |
---|---|
200 |
The request was successful. |
400 |
The request was invalid and/or malformed. The response will contain an Errors 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. |
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. |
Generate Recovery Codes
This API is used to generate a list of Recovery Codes. When creating new codes, any existing Recovery Codes will be cleared and the new set will become the current values.
Request
POST /api/user/two-factor/recovery-code/{userId}
Request Parameters
- userId [UUID] Required
-
The unique Id of the user to assign the generated Recovery Codes to.
Response
The response for this API contains an array of size 10 of Recovery Codes that were created.
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 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. |
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
- 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"
]
}
Retrieve Recovery Codes
This API is used to retrieve Recovery Codes for a User.
Request
GET /api/user/two-factor/recovery-code/{userId}
Request Parameters
- userId [UUID] Required
-
The Id of the User to retrieve Recovery Codes for.
Response
The response for this API contains the remaining Recovery Codes that are assigned to the User. Each time one is used it is removed, so this response will contain between 0 and 10 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 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. |
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
- 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"
]
}
Feedback
How helpful was this page?
See a problem?
File an issue in our docs repo
Have a question or comment to share?
Visit the FusionAuth community forum.