Backup codes

Concepts

Backup codes, also known as Recovery code, is a one-time use code for MFA, acting as a backup in case the user's primary authentication factors (e.g., authenticator app or hardware token) are unavailable.

Losing them can lead to account recovery challenges. Therefore, it's recommended to set up an additional primary factor before enabling Backup Codes, giving it priority.

Logto automatically generates 10 Backup Codes for users once they configure an additional factor. Each code is single-use. Users are advised to regenerate a new set of codes in the User Account Settings (accessible through the Management API) before using up all the existing codes.

Configure backup codes for MFA

1. Navigate to Console > Multi-factor authentication
2. Enable the "Backup Codes" factor. Backup codes cannot be used as the sole MFA factor. It is required to use backup codes in combination with other primary MFA factors (passkeys, authenticator app, SMS, email).
3. Configure your preferred MFA policy (required vs. optional)
4. Save your configuration changes

Configure backup codes management

You can use the Account API to build custom account management interfaces where users can view, regenerate, and remove their backup codes. This enables users to manage their recovery options directly from your application's account settings.

For detailed implementation steps and API endpoints, see Account settings by Account API.

Backup codes setup flows

Due to backup codes being a secondary MFA factor, they can only be set up after a primary MFA factor has been successfully configured. A group of 10 auto-generated backup codes will be displayed to the user, which they can download and copy securely. User must manually confirm the backup codes to complete the MFA setup process.

Backup codes verification flow

Backup codes serve as emergency authentication when primary MFA factors are unavailable. Each code can only be used once and becomes invalid after successful verification.

Verification priority:

• Primary factors first: When users have other MFA factors configured, primary factors (passkeys, TOTP, SMS, email) are prompted first.
• Backup code access: Users can switch to backup codes by clicking "Try another method to verify" if primary factors are unavailable.
• Fallback scenario: If all primary factors are deleted, backup codes become the only verification option. After successful MFA verification via backup codes during sign-in, Logto automatically prompts users to set up a new primary factor.