Complete Multi-Factor Authentication

Edit on GitHubEdit MD

The Multi-Factor Login API is used to complete the authentication process when a 242 status code is returned by the Login API or as the last step of a Step Up Procedure.

Request#

Complete a login request when a User has Multi-Factor authentication enabled.

Complete a Multi-Factor Login

OpenAPI Spec

Request Headers#

X-Forwarded-For String optional

The IP address of a client requesting authentication. If the IP address is provided it will be stored for login history of the user. It is generally preferred to specify the IP address in the request body. If it is not provided in the request body, this header value will be used if available. If provided in both places, the request body value takes precedence.

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

The Id of the Application the user is to be logged into. This parameter is optional but there is not likely a production use case where you want to omit the value. If this parameter is omitted the user will still be authenticated but a login count will not be recorded for an Application.

See the difference between authentication and authorization for more detail.

code String required

The Multi-Factor verification code. This may also be a recovery code.

ipAddress String optional

The IP address of the end-user that is logging into FusionAuth. If this value is omitted FusionAuth will attempt to obtain the IP address of the client, the value will be that of the X-Forwarded-For header if provided or the last proxy that sent the request. The IP address will be stored in the User login history.

metaData.device.description String optional

A human readable description of the device used. This meta data is used to describe the refresh token that may be generated for this request.

metaData.device.lastAccessedAddress String optional

The IP address which made this request.

metaData.device.name String optional

A human readable name of the device used. This meta data is used to describe the refresh token that may be generated for this request.

metaData.device.type String optional

The type of device represented by the device parameter.

Prior to version 1.46.0, this value was restricted to the following types:

BROWSER
DESKTOP
LAPTOP
MOBILE
OTHER
SERVER
TABLET
TV
UNKNOWN

In version 1.46.0 and beyond, this value can be any string value you'd like, have fun with it!

This meta data is used to describe the refresh token that may be generated for this request.

noJWT Boolean optional Defaults to false

When this value is set to true a JWT will not be issued as part of this request. The response body will not contain the token field, and the access_token and refresh_token cookies will not be written to the HTTP response.

trustComputer Boolean optional Defaults to false

When this value is set to true the response will contain a Multi-Factor Trust identifier. This can be used on subsequent Login requests to allow the Multi-Factor challenge to be bypassed.

twoFactorId String required

An Id generated and returned in the response body during the initial authentication attempt.

The default duration of this identifier is 5 minutes. This means that you have 5 minutes to complete the request to this API after calling the Login API. Once the identifier has expired you will need to call the Login API again to restart the process.

This duration can be modified using the Tenant API or in the FusionAuth UI.

Example Request JSON

{
  "applicationId": "10000000-0000-0002-0000-000000000001",
  "code": "915187",
  "ipAddress": "192.168.1.42",
  "twoFactorId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}

Response#

The response for this API contains the User object.

Response Codes

Code	Description
200	The authentication was successful. The response will contain the User object that was authenticated.
202	The user was authenticated successfully. The user is not registered for the application specified by `applicationId` on the request. The response will contain the User object that was authenticated.
203	The user was authenticated successfully. The user is required to change their password, the response will contain the `changePasswordId` to be used on the Change Password API. Since version `1.15.0`, the response will also contain a `changePasswordReason` field which can have one of the following values: `Administrative` - An administrator has required this user to change their password. `Breached` - The password has been found to have belonged to a breached dataset and must be changed, per the Reactor configuration. `Expired` - The password has expired, per the expiration setting in the tenant configuration. `Validation` - The password fails the validation rules configured in the tenant password settings. Example Response JSON `{ "changePasswordId": "XOgai4Ro68xfGiex0ngXiJ2bbhduM4Pm7h3lvF0xibQ", "changePasswordReason": "Expired" }`
212	The user's email address (if an email address or username was used to authenticate) or phone number has not yet been verified. The response will contain the User object that was authenticated. If the tenant verification strategy has been set to `FormField`, the response will contain the verification Id that was generated for the user.
213	The user's registration has not yet been verified. The response will contain the User object that was authenticated. If the verification strategy has been set to `FormField`, the response will contain the registrationVerificationId that was generated for the user. Prior to version `1.27.0`, this status code was not returned, and you will see a `200` instead.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
404	The `twoFactorId` was invalid or expired. You will need to authenticate again using the Login API. The response will be empty.
409	The user is currently in an action that has prevented login. The response will contain the actions that prevented login. Example Response JSON `{ "actions": [ { "actionId": "00000000-0000-0000-0000-000000000042", "actionerUserId": "00000000-0000-0001-0000-000000000000", "expiry": 1571786483322, "localizedName": "Prevent Login Action", "localizedReason": "Hard Lock", "name": "Prevent Login Action", "reason": "Hard Lock", "reasonCode": "hard_lock" } ] }`
410	The user has expired. The response will be empty.
421	The `code` request parameter is not valid. 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.
504	One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

emailVerificationId String

An email verification Id, which is needed when performing your own email verification using the /api/user/verify-email API.

This field is only returned when the tenant.emailConfiguration.verificationStrategy is set to FormField.

identityVerificationId String Available since 1.59.0

An identity verification Id, which is needed when performing your own identity verification using the /api/identity/verify API.

This field is only returned under the following conditions, based on the identity that was used to log in:

An email address - the tenant.emailConfiguration.verificationStrategy is set to FormField.
A phone number - the tenant.phoneConfiguration.verificationStrategy is set to FormField.

refreshToken String

The refresh token that can be used to obtain a new access token once the provided one has expired.

Because a refresh token is per user and per application, this value will only be returned when an applicationId was provided on the login request and the user is registered to the application.

You must explicitly allow generation of refresh tokens when using the Login API.

Configure the application.loginConfiguration.generateRefreshTokens setting via the API or enable the setting by navigating to the Application -> My Application -> Security tab.

refreshTokenId String Available since 1.37.0

When the refreshToken is returned in the response, this field will also be returned. This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the Refresh Token API.

state Object Available since 1.26.0

If authenticated using Two-Factor and state was provided during the Two-Factor Start request this value will be returned exactly as it was provided.

trustToken String Available since 1.33.0

A trust token that may be used to complete another API request that requires trust. For example, if you receive an error from an API indicating trust is required - indicated by this error code [TrustTokenRequired], this value can be used to satisfy the trust requirement.

twoFactorTrustId String

The Two-Factor Trust identifier. This value is returned when trustComputer was set to true on the request. This value can be used by subsequent login requests to bypass the Two-Factor challenge.

token String Available since 1.16.0

The access token, this string is an encoded JSON Web Token (JWT).

When the user will be sent a setup password email or sms message, this token will not be returned.

tokenExpirationInstant Long Available since 1.33.0

The instant the token will expire. If the response does not contain a token, this field will also be omitted from the response.

user.active Boolean

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to log in.

user.birthDate String

The User's birthdate formatted as YYYY-MM-DD

user.breachedPasswordLastCheckedInstant Long

The instant this user's password was last checked to determine if it is compromised.

user.connectorId UUID Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

user.cleanSpeakId UUID

This Id is used by FusionAuth when the User's username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.data Object

An object that can hold any information about the User that should be persisted.

user.data.email String

This field will be used as the email address if no user.email field is found.

This feature was removed in version 1.26.0 and added back in 1.27.2.

user.email String

The User's email address.

user.expiry Long

The expiration instant of the User's account. An expired user is not permitted to log in.

user.firstName String

The first name of the User.

user.fullName String

The User's full name as a separate field that is not calculated from firstName and lastName.

user.id UUID

The User's unique Id.

user.identities Array Available since 1.59.0

The list of identities that exist for a User.

user.identities[x].displayValue String Available since 1.59.0

The display value for the identity. Only used for username type identities. If the unique username feature is not enabled, this value will be the same as user.identities[x].value. Otherwise, it will be the username the User has chosen. For primary username identities, this will be the same value as user.username.

user.identities[x].insertInstant Long Available since 1.59.0

The instant when the identity was created.

user.identities[x].lastLoginInstant Long Available since 1.59.0

The instant when the identity was last used to log in. If a User has multiple identity types (username, email, and phoneNumber), then this value will represent the specific identity they last used to log in. This contrasts with user.lastLoginInstant, which represents the last time any of the User's identities was used to log in.

note

Identity provider logins will not be reflected here (see user.lastLoginInstant for a field that includes identity provider logins).

user.identities[x].lastUpdateInstant Long Available since 1.59.0

The instant when the identity was last updated.

user.identities[x].moderationStatus String Available since 1.59.0

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

ACTIVE - the username is active
PENDING - the username is pending approval/moderation
REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

Only used for username type identities. For primary username identities, this will be the same value as user.usernameStatus.

user.identities[x].type String Available since 1.59.0

The identity type. The possible values are:

email - identities defined by an email address
phoneNumber - identities defined by a phone number
username - identities defined by a username

user.identities[x].value String Available since 1.59.0

The value represented by the identity. The contents of this field depend on user.identities[x].typeand will be one of the following:

Email address - The User's email address, always lower cased. For primary email identities, this will be the same value as user.email
Phone number - The User's phone number, in E.164 canonical format. For primary phone number identities, this will be the same value as user.phoneNumber
Username - User's username - this will be the same as user.identities[x].displayValue. For primary username identities, this will be the same value as user.username

This value is unique within a tenant for a particular user.identities[x].type.

note

If the unique usernames feature is enabled, value will be the unique username (within the tenant). For primary username identities, this will also be the same value as user.uniqueUsername.

user.identities[x].verified Boolean Available since 1.59.0

Whether verification was actually performed on the identity by FusionAuth. This is used in combination with the user.identities[x].verifiedReason to decide whether an identity needs verification.

user.identities[x].verifiedInstant Long Available since 1.59.0

The instant when verification was performed on the identity. This field is only populated when verification was actually performed on the identity by FusionAuth.

user.identities[x].verifiedReason String Available since 1.59.0

The reason the User's identity was verified or not verified. The possible values are:

Skipped - Verification was skipped due to the skipVerification parameter on the request
Trusted - Identity was created via an identity provider or a connector
Unverifiable - FusionAuth doesn't know how to verify this identity type. Usernames are an example
Implicit - Verification was implicitly performed by sending a set password or passwordless message
Pending - Tenant policy requires verification but no verification has been performed yet
Completed - Verification was performed by FusionAuth
Disabled - Tenant policy did not require verification
Import - User was imported so verification was not performed by FusionAuth

If this field is Disabled, Import, Skipped, Trusted, or Unverifiable, then verification will not be required, regardless of the user.identities[x].verified value. For Implicit, Pending, or Completed, the identity will require verification if user.identities[x].verified is false.

user.imageUrl String

The URL that points to an image file that is the User's profile image.

user.insertInstant Long

The instant when the user was created.

user.lastLoginInstant Long

The instant when the User logged in last. See user.identities[x].lastLoginInstant for more granular information based on identity.

user.lastName String

The User's last name.

user.lastUpdateInstant Long

The instant when the User was last updated.

user.legacyIdentifier String Available since 1.67

Used to override the sub claim in tokens issued by the Legacy Identity Provider Adapter.

This value is immutable after the user is created and is unique within the tenant when non-null.

user.memberships Array

The list of memberships for the User.

user.memberships[x].data Object

An object that can hold any information about the User for this membership that should be persisted.

user.memberships[x].groupId UUID

The Id of the Group of this membership.

user.memberships[x].id UUID

The unique Id of this membership.

user.memberships[x].insertInstant Long

The instant that the membership was created.

user.middleName String

The User's middle name.

user.mobilePhone String

The User's mobile phone number. This is useful if you will be sending push notifications or SMS messages to the User.

note

This differs from user.phoneNumber and cannot be used to log in.

user.parentEmail String Available since 1.7.0

The email address of the user's parent or guardian. If this value was provided during a create or update operation, this value will only remain until the child is claimed by a parent.

user.passwordChangeRequired Boolean

Indicates that the User's password needs to be changed during their next login attempt.

user.passwordLastUpdateInstant Long

The instant that the User last changed their password.

note

Since version 1.59.0, if a user does not currently have a password, this field will not be returned in the response.

user.phoneNumber String Available since 1.59.0

The User's primary phone number. The phone number is stored and returned in E.164 canonical format, however a phone number is considered unique regardless of the format. 303-555-1212 is considered equal to +13035551212 so either version of this phone number can be used whenever providing it as input to an API.

note

This differs from user.mobilePhone in that user.phoneNumber can be used to log in, just like an email address or a username.

user.preferredLanguages Array<String>

An array of locale strings that give, in order, the User's preferred languages. These are important for email templates and other localizable text. See Locales.

user.registrations Array

The list of registrations for the User. This will include registrations for inactive applications.

user.registrations[x].applicationId UUID

The Id of the Application that this registration is for.

user.registrations[x].authenticationToken String

The Authentication Token for this registration (if one exists).

user.registrations[x].cleanSpeakId UUID

This Id is used by FusionAuth when the User's username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.registrations[x].data Object

An object that can hold any information about the User for this registration that should be persisted.

user.registrations[x].id UUID

The Id of this registration.

user.registrations[x].insertInstant Long

The instant that this registration was created.

user.registrations[x].lastLoginInstant Long

The instant that the User last logged into the Application for this registration.

user.registrations[x].preferredLanguages Array<String>

An array of locale strings that give, in order, the User's preferred languages for this registration. These are important for email templates and other localizable text.

user.registrations[x].roles Array<String>

The list of roles that the User has for this registration. The string is the role's Name not the role's Id, e.g. admin or user-role.

user.registrations[x].timezone String

The User's preferred timezone for this registration. The string will be in an IANA time zone format.

user.registrations[x].tokens Map<String,String DEPRECATED

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

user.registrations[x].username String

The username of the User for this registration only. This is for display purposes and cannot be used to log in.

user.registrations[x].usernameStatus String

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

ACTIVE - the username is active
PENDING - the username is pending approval/moderation
REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.registrations[x].verified Boolean

This value indicates if this User's registration has been verified.

For additional information, see these tutorials:

user.registrations[x].verifiedInstant Long Available since 1.48.0

The instant that this registration was verified.

user.tenantId UUID

The Id of the Tenant that this User belongs to.

user.timezone String

The User's preferred timezone. This can be used as a default to display instants, and it is recommended that you allow Users to change this per-session. The string will be in an IANA time zone format.

user.twoFactor.methods[x].authenticator.algorithm String

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLength Integer

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStep Integer

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].email String

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].id String

The unique Id of the method.

user.twoFactor.methods[x].lastUsed Boolean

true if this method was used most recently.

user.twoFactor.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

user.twoFactor.methods[x].mobilePhone String

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactorDelivery String DEPRECATED

The User's preferred delivery for verification codes during a two-factor login request.

The possible values are:

None
TextMessage

Removed in 1.26.0

user.twoFactorEnabled Boolean DEPRECATED

Determines if the User has two-factor authentication enabled for their account or not.

Removed in 1.26.0

user.username String

The username of the User.

user.usernameStatus String

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

ACTIVE - the username is active
PENDING - the username is pending approval/moderation
REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.verified Boolean DEPRECATED

Whether or not the User's primary email identity has been verified. This does NOT indicate whether phone number identity types are verified.

For additional information, see these tutorials:

Deprecated since 1.59.0

See user.identities[x].verified and user.identities[x].verifiedReason.

user.verifiedInstant Long Available since 1.48.0

The first instant that the User's primary email address or phone number was verified. This value is immutable and cannot change for a user once set.

Example Response JSON

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "breachedPasswordLastCheckedInstant": 1471786483322,
    "breachedPasswordStatus": "None",
    "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "identities": [
      {
        "insertInstant": 1742936980069,
        "lastLoginInstant": 1742936980069,
        "lastUpdateInstant": 1742936980069,
        "primary": true,
        "type": "email",
        "value": "example@fusionauth.io",
        "verified": false,
        "verifiedReason": "Disabled"
      },
      {
        "insertInstant": 1742936980069,
        "lastLoginInstant": 1742936980069,
        "lastUpdateInstant": 1742936980069,
        "primary": true,
        "type": "phoneNumber",
        "value": "+13035551212",
        "verified": false,
        "verifiedReason": "Disabled"
      },
      {
        "displayValue": "johnny123",
        "insertInstant": 1742936980069,
        "lastLoginInstant": 1742936980069,
        "lastUpdateInstant": 1742936980069,
        "moderationStatus": "ACTIVE",
        "primary": true,
        "type": "username",
        "value": "johnny123",
        "verified": false,
        "verifiedReason": "Unverifiable"
      }
    ],
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "insertInstant": 1742936980069,
    "lastLoginInstant": 1742936980069,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1742936980069,
    "phoneNumber": "+13035551212",
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1742936980069,
        "lastLoginInstant": 1742936980069,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "username": "johnny123",
        "usernameStatus": "ACTIVE",
        "verified": true,
        "verifiedInstant": 1742936980069
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "id": "35VW",
          "method": "authenticator"
        },
        {
          "id": "V7SH",
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "id": "7K2G",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true,
    "verifiedInstant": 1742936980069
  }
}

Response Cookies#

access_token String

The encoded access token. This cookie is written in the response as an HTTP Only session cookie.

refresh_token String

The refresh token. This cookie is written in the response as an HTTP Only persistent cookie. The cookie expiration is configured in the JWT configuration for the application or the global JWT configuration.

fusionauth.trust String

The Multi-Factor Trust identifier. This value is returned when trustComputer was set to true on the request. This value can be used by subsequent login requests to bypass the Multi-Factor challenge. This cookie is written in the response as an HTTP Only persistent cookie.