FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    Multi-Factor/Two Factor APIs

    FusionAuth Reactor logo

    Email and SMS two-factor methods are only available in paid editions of FusionAuth. Please visit our pricing page to learn more about paid editions.

    Overview

    This API allows you to manage Multi-Factor authentication (MFA) for users.

    This API underwent breaking changes in version 1.26. You can view the 1.25 Two Factor documentation if needed.

    • Authentication

    • TOTP Implementation

    • Enable Multi-Factor

    • Disable Multi-Factor

    • Generate a Secret

    • Start Multi-Factor

    • Retrieve Multi-Factor Status

    • Send a Multi-Factor Code During Login or Step Up

    • Send a Multi-Factor Code When Enabling MFA

    • Send a Multi-Factor Code When Disabling MFA

    • Generate Recovery Codes

    • Retrieve Recovery Codes

    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.

    Learn more about JWT authentication and see examples here.

    In some cases, when you have a valid twoFactorId, neither a JWT nor an API key is required.

    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

    authenticator.algorithm

    HmacSHA1

    authenticator.codeLength

    6

    authenticator.timeStep

    30

    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 With a UserId

    URI

    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

    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.

    Example Request JSON Enabling a TOTP Factor
    
    {
      "code": "435612",
      "method": "authenticator",
      "secret": "8MJJfCY4ERBtotvenSc3"
    }
    Example Request JSON Enabling an Email Factor
    
    {
      "code": "435612",
      "method": "email",
      "email": "richard@piedpiper.com"
    }

    Enable Multi-Factor Authentication Using a JWT

    URI

    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

    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.

    Example Request JSON Enabling a TOTP Factor
    
    {
      "code": "435612",
      "method": "authenticator",
      "secret": "8MJJfCY4ERBtotvenSc3"
    }
    Example Request JSON Enabling an Email Factor
    
    {
      "code": "435612",
      "method": "email",
      "email": "richard@piedpiper.com"
    }

    Response

    Table 1. Response Codes
    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 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.

    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.

    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.

    Example Response JSON with recovery codes.
    
    {
      "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 Multi-Factor Authentication With a UserId

    URI

    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

    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.

    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 Multi-Factor Authentication Using a JWT

    URI

    DELETE /api/user/two-factor?code={code}&methodId={methodId}

    Request Parameters

    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.

    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

    Table 2. Response Codes
    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 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.

    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

    URI

    GET /api/two-factor/secret

    Generate a Multi-Factor Secret

    URI

    GET /api/two-factor/secret

    Response

    The response for this API contains a Multi-Factor secret suitable for an authenticator like Google Authenticator.

    Table 3. Response Codes
    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.

    Example Response JSON
    
    {
      "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

    URI

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

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

    Response

    Table 4. Response 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.

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

    Example Response JSON With Methods Configured
    
    {
      "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"
    }
    Example Request JSON With No Methods Configured
    
    {
      "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

    URI

    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.

    Example Request JSON
    
    {
      "methodId": "KLRT"
    }

    Response

    This API does not return a JSON response body.

    Table 5. Response Codes
    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 two-factor enabled, and if the user will be required to perform a two-factor challenge during the next login request.

    This API may also be used to identify if an existing two-factor trust value obtained during a two-factor login is expired, or valid for a specific application when an Application has been configured to restrict two-factor trust.

    Request

    Retrieve Multi-Factor Status

    URI

    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 two-factor trust obtained by completing a two-factor login. This is the value that allows you to bypass two-factor during the next login attempt.

    userId [String] Required

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

    Response

    Table 6. Response Codes
    Code Description

    200

    The user does not have two-factor enabled, or the provided trust is still valid for the next login.

    242

    The user has two-factor authentication enabled, and will be required to complete a two-factor challenge during the next login attempt.

    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.

    Example Response JSON
    
    {
      "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

    URI

    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.

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

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

    URI

    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.

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

    Response

    This API does not return a JSON response body.

    Table 7. Response Codes
    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

    URI

    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.

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

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

    URI

    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.

    Example Request JSON
    
    {
      "methodId": "RLRT"
    }

    Response

    This API does not return a JSON response body.

    Table 8. Response Codes
    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

    Create Recovery Codes

    URI

    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.

    Table 9. Response 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.

    Example Response JSON
    
    {
      "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

    Retrieve Recovery Codes

    URI

    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.

    Table 10. Response 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.

    Example Response JSON
    
    {
      "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.

    © 2023 FusionAuth
    Subscribe for developer updates