Supascale
Sign Up

2FA Recovery

How to recover access when locked out of two-factor authentication.

If you've lost access to your authenticator app and don't have backup codes, you can use the emergency disable script to regain access to your Supascale account.

Recovery Options

Option 1: Use a Backup Code

If you saved your backup codes when setting up 2FA:

  1. At the login verification prompt, enter a backup code
  2. Backup codes are 8-character alphanumeric codes (e.g., A1B2C3D4)
  3. After logging in, set up 2FA again with a new authenticator

Option 2: Emergency Disable Script

If you don't have backup codes, use the server-side disable script.

Emergency 2FA Disable

Prerequisites

  • SSH access to your server
  • Access to the Supascale installation directory

Disable Steps

  1. SSH into your server:

    ssh user@your-server

  2. Navigate to the Supascale directory:

    cd /opt/supascale-web

  3. Run the disable script:

    node scripts/disable-totp.js <username>

    Or run interactively:

    node scripts/disable-totp.js

  4. Confirm the action when prompted

  5. Log in with just your password

  6. Re-enable 2FA in Settings > Profile for continued security

Example Output

=== Supascale TOTP 2FA Disable ===

WARNING: This will disable two-factor authentication for the specified user.
Only use this if the user has lost access to their authenticator app
AND all backup codes.

Enter username to disable 2FA for: admin

User: admin
2FA Status: ENABLED

Are you sure you want to disable 2FA for this user? (yes/no): yes

SUCCESS: Two-factor authentication has been disabled for user: admin

The user can now log in with just their password.
They should set up 2FA again after logging in for improved security.

Script Reference

Usage

# Direct usage with username
node scripts/disable-totp.js admin

# Interactive mode (prompts for username)
node scripts/disable-totp.js

Options

ArgumentDescription
usernameThe username to disable 2FA for

What It Does

The script:

  1. Verifies the user exists
  2. Checks if 2FA is currently enabled
  3. Prompts for confirmation
  4. Clears the TOTP secret, backup codes, and enabled flag
  5. Logs the action to the activity log

Activity Log Entry

The script creates an activity log entry:

{
  "type": "auth",
  "action": "totp_disabled_by_admin",
  "details": {
    "username": "admin",
    "disabledAt": "2026-01-26T12:00:00.000Z"
  }
}

Troubleshooting

"User not found"

Error:

ERROR: User not found: admin

Solution: Check the correct username:

sqlite3 /opt/supascale-web/data/supascale.db "SELECT username FROM users;"

"2FA is not enabled"

Message:

INFO: Two-factor authentication is not enabled for user: admin

This means 2FA is already disabled. You can log in with just your password.

"Database not found"

Error:

ERROR: Database not found at /opt/supascale-web/data/supascale.db

Solution: Make sure you're running the script from the correct directory:

# Find Supascale installation
find /opt -name "supascale-web" -type d 2>/dev/null

# Or check PM2
pm2 show supascale-web | grep "script path"

"Database locked"

Error:

SQLITE_BUSY: database is locked

Solution: The application might be writing to the database. Try:

# Stop the application first
pm2 stop supascale-web

# Run the script
node scripts/disable-totp.js admin

# Restart the application
pm2 start supascale-web

Permission Denied

Error:

EACCES: permission denied

Solution: Run with the correct user or sudo:

# Check file ownership
ls -la /opt/supascale-web/data/

# Run with sudo if needed
sudo node scripts/disable-totp.js admin

Direct Database Method (Advanced)

If the script is unavailable, you can disable 2FA directly in the database:

# Stop the application
pm2 stop supascale-web

# Open SQLite
sqlite3 /opt/supascale-web/data/supascale.db

# Disable 2FA
UPDATE users
SET totp_secret = NULL,
    totp_enabled = 0,
    totp_backup_codes = NULL,
    totp_verified_at = NULL
WHERE username = 'admin';

# Verify
SELECT username, totp_enabled FROM users WHERE username = 'admin';

# Exit
.quit

# Restart
pm2 start supascale-web

Security Considerations

After Recovery

  1. Re-enable 2FA immediately after logging in
  2. Save backup codes in a secure location this time
  3. Check activity log for any unauthorized access attempts
  4. Review API keys and revoke any suspicious ones

Prevention

To avoid future lockouts:

  1. Store backup codes securely - Use a password manager
  2. Print backup codes - Keep a physical copy in a safe
  3. Use multiple devices - Some authenticator apps sync across devices
  4. Export TOTP secrets - Some apps allow exporting/backing up secrets