TOTP Backup Codes and Recovery

TOTP Backup Codes: Preventing Account Lockout

Backup codes (also called recovery codes) are one-time-use codes that allow users to access their account when they cannot generate a TOTP code — typically because they have lost their phone or uninstalled their authenticator app.

Why Backup Codes Are Essential

Without backup codes, a user who loses access to their authenticator has no way to log in. This creates one of the worst user experience scenarios in authentication:

• Device loss: phone stolen, broken, or factory reset
• App deletion: accidentally uninstalling the authenticator
• Device migration: getting a new phone without exporting TOTP accounts
• App malfunction: authenticator app data corruption

Generating Backup Codes

Backup codes should be:

• Cryptographically random: use a CSPRNG, not sequential numbers
• Sufficiently long: 8-10 alphanumeric characters per code
• Unique per user: never share codes between accounts
• Provided in sets: typically 8-10 codes per generation

import secrets
import string

def generate_backup_codes(count=10, length=8):
    alphabet = string.ascii_lowercase + string.digits
    codes = []
    for _ in range(count):
        code = ''.join(secrets.choice(alphabet) for _ in range(length))
        # Format as xxxx-xxxx for readability
        codes.append(f"{code[:4]}-{code[4:]}")
    return codes

Storage and Security

On the server side:

• Hash each code (bcrypt or SHA-256 with salt) before storing
• Mark codes as used after redemption — they are single-use
• Store the hash, not the plaintext — treat backup codes like passwords
• Allow regeneration — users should be able to invalidate old codes and get new ones

User Experience Best Practices

1. Display once: show codes immediately after 2FA enrollment, clearly stating they will not be shown again
2. Download option: provide a "Download as text file" button
3. Copy button: one-click copy all codes to clipboard
4. Confirmation: require the user to confirm they have saved the codes before proceeding
5. Count display: show remaining unused codes on the security settings page
6. Regeneration: allow users to generate a new set (invalidating the old ones)

Recovery Flow

When a user attempts to log in without their authenticator:

1. Present a "Lost your device?" or "Use backup code" option
2. Accept a backup code in place of the TOTP code
3. Mark that backup code as consumed
4. After login, strongly encourage re-enrollment with a new device
5. Consider requiring password verification alongside the backup code