> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging.auth0-mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

> Describes how to import MFA enrollments for your existing users.

# Import User MFA Authenticator Enrollments

You can import a user's <Tooltip tip="Multi-factor authentication (MFA): User authentication process that uses a factor in addition to username and password such as a code via SMS." cta="View Glossary" href="/docs/glossary?term=MFA">MFA</Tooltip> enrollments with [automatic migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) and [bulk user imports](/docs/manage-users/user-migration/bulk-user-imports). The supported enrollment types are:

* Email: for email verification.
* Phone: for SMS verification.
* OTP: for One-Time Passwords (OTPs) used with authenticator applications, such as Google Authenticator.

Importing MFA enrollments provides a seamless user experience, since users won't have to re-enroll after migration.

The classic login experience does not support factor selection for users with multiple factors. If you plan to import users with multiple registered factors, consider using the [Universal Login](/docs/authenticate/login/auth0-universal-login) experience.

## Schema

The schema applies to MFA factors for both of the following workflows.

```json lines expandable theme={null}
{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "totp": {
                "type": "object",
                "properties": {
                "secret": {
                    "type": "string",
                        "pattern": "^[A-Z2-7]+$",
                        "description": "The OTP secret is used for MFA authentication with Google Authenticator type apps. It must be supplied in un-padded Base32 encoding, such as: JBTWY3DPEHPK3PNP"
                    },
                },
                "additionalProperties": false,
                "required": ["secret"],
            },
            "phone": {
                "type": "object",
                "properties": {
                "value": {
                    "type": "string",
                    "pattern": "^\\+[0-9]{1,15}$",
                    "description": "The phone number for SMS or Voice MFA. The phone number should include a country code and begin with +, such as: +12125550001"
                },
                },
                "additionalProperties": false,
                "required": ["value"],
            },
            "email": {
                "type": "object",
                "properties": {
                    "value": {
                        "type": "string",
                        "format": "email",
                        "description": "The email address for MFA"
                    },
                },
                "additionalProperties": false,
                "required": ["value"],
            },
        },
        "maxProperties": 1,
        "additionalProperties": false,
    },
    "minItems": 1,
    "maxItems": 10
}
```

## Automatic migration

MFA enrollments can also be imported during an [automatic migration](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections#automatic-migration-scenario). This can be accomplished by providing any existing enrollments in the `mfa_factors` field of the user that is provided to the callback at the end of your custom DB [login script](/docs/authenticate/database-connections/custom-db/templates/login).

Any failures will appear in your tenant logs as failed logins, and will be distinguishable from other failures by their description: `Unable to import MFA factors`. For example:

```json lines theme={null}
{
  "_id": "5e9df3b29ebabe00571c04a7",
  "date": "2020-04-20T19:10:42.916Z",
  "type": "fu",
  "description": "Unable to import MFA factors.",
  "connection": "Username-Password-Authentication",
  "connection_id": "con_mMkvaycgzgCS0p0z",
  "client_id": "aCbTAJNi5HbsjPJtRpSP6BIoLPOrSj2Cgg",
  "client_name": "All Applications",
  "ip": "10.12.13.1",
  "client_ip": null,
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
  "details": {
    "error": {
      "message": "Unable to import MFA factors."
    }
  },
  "user_name": "test@test.io",
  "strategy": "auth0",
  "strategy_type": "database"
}
```

## Bulk user import

1. Prepare a `users.json` file. See [bulk user imports](/docs/manage-users/user-migration/bulk-user-imports) for details.
2. Include existing MFA enrollments for each user.
3. Start a bulk user import.
4. Update the factors of any existing users by enabling the `upsert` option in your initial request.
5. Once the import job completes, check the response for any errors. If any of the users' MFA factors failed to import, you will see errors such as:

When using the `upsert` option, any non-MFA related updates to existing users will have been applied to the user's profile. For example, the following error summary shows the user's `picture` attribute was successfully set to `http://example.org/jdoe.png`, however we were unable to import the provided MFA factors. In cases like this, it is safe to retry the import for failed users.

```json lines expandable theme={null}
[
  {
    "user": {
      "email": "antoinette@contoso.com",
      "picture": "http://example.org/jdoe.png",
      "mfa_factors": [
        {
          "totp": {
            "secret": "2PRXZWZAYYDAWCD"
          }
        },
        {
          "phone": {
            "value": "+15551112233"
          }
        },
        {
          "email": {
            "value": "antoinette@antoinette.biz"
          }
        }
      ]
    },
    "errors": [
      {
        "code": "MFA_FACTORS_FAILED",
        "message": "Unable to import factors"
      }
    ]
  }
]
```

## Recovery codes

Auth0 does not provide a way to import recovery codes. When the user's MFA factors are imported, they won't have a recovery code.

To provide users a recovery code, you can check if they have one enrolled, and if not, use the [Recovery Code Regeneration endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_recovery_code_regeneration) to generate a new one.

## Learn more

* [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database)
* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)