Backup Codes

Backup codes are one-time-use recovery codes that let you sign in when you lose access to your primary two-factor authentication device. They act as a safety net, ensuring you are never permanently locked out of your account.

What Are Backup Codes?

When you enable two-factor authentication (TOTP, email OTP, or SMS), UniAuth generates a set of 8 backup codes. Each code is a random alphanumeric string that can be used exactly once in place of your normal 2FA code. Think of them as emergency keys — you keep them somewhere safe and use them only when your authenticator app, phone, or email is unavailable.

Backup codes are hashed with SHA-256 before storage, so UniAuth cannot retrieve or display them after the initial generation. This is why it is critical to save them immediately.

Generating Backup Codes

Backup codes are generated automatically when you enable any 2FA method for the first time. You can also regenerate them at any time from your security settings.

1. Navigate to Account → Security.
2. Enable a 2FA method (TOTP, Email, or SMS) if you have not already.
3. After successful 2FA setup, your 8 backup codes are displayed on screen.
4. Copy or download them immediately — they will not be shown again.

The API response when 2FA setup completes includes the codes:

POST /api/auth/2fa/setup
Content-Type: application/json

{
  "method": "totp"
}

// After verifying the TOTP code, the response includes:
{
  "success": true,
  "backupCodes": [
    "a1b2c3d4e5",
    "f6g7h8i9j0",
    "k1l2m3n4o5",
    "p6q7r8s9t0",
    "u1v2w3x4y5",
    "z6a7b8c9d0",
    "e1f2g3h4i5",
    "j6k7l8m9n0"
  ]
}

Storing Backup Codes Safely

Backup codes are only useful if you can find them when you need them. Follow these best practices:

• Password manager — Store the codes as a secure note in your password manager (1Password, Bitwarden, etc.). This is the most convenient option for most users.
• Print a hard copy — Print the codes and store the paper in a secure location such as a safe or locked drawer.
• Encrypted file — Save the codes in an encrypted file on a separate device or USB drive.
• Do not store backup codes in plain text on your computer, in email drafts, or in cloud notes without encryption.

Using a Backup Code

When you sign in and are prompted for a 2FA code, you can enter a backup code instead of the code from your authenticator app, email, or SMS.

1. Enter your email and password as usual.
2. When the 2FA prompt appears, enter one of your backup codes in the code field.
3. Click Verify.
4. If the code is valid, you are signed in. That code is immediately consumed and cannot be reused.

The API accepts backup codes through the same verification endpoint:

POST /api/auth/2fa/verify
Content-Type: application/json

{
  "userId": "your-user-id",
  "code": "a1b2c3d4e5",
  "method": "totp"
}

// The server automatically detects whether the code is a TOTP code
// or a backup code and handles it accordingly.

Each backup code is single-use. Once consumed, it is marked as used and will be rejected on subsequent attempts. You can see how many unused codes remain in your security settings.

Regenerating Backup Codes

If you have used most of your backup codes or suspect they have been compromised, you should regenerate them. Regeneration creates a fresh set of 8 codes and immediately invalidates all previous codes.

1. Navigate to Account → Security.
2. In the Two-Factor Authentication section, click Regenerate Backup Codes.
3. Confirm the action. All existing codes are revoked.
4. Save the new codes immediately using the best practices above.

For Developers

If you are integrating with the UniAuth API, backup codes require no special handling. They are accepted by the same POST /api/auth/2fa/verify endpoint used for TOTP, email, and SMS codes. The server inspects the code format and checks it against both the active 2FA method and the stored backup code hashes.

The verification flow for your application should look like this:

// 1. User logs in — receives requires2FA: true
const loginRes = await fetch('https://uniauth.id/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});
const { requires2FA, userId } = await loginRes.json();

// 2. User enters their code (TOTP, OTP, or backup code)
const verifyRes = await fetch('https://uniauth.id/api/auth/2fa/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId, code: userInput, method: 'totp' })
});

// 3. If successful, the session cookie is set
const { success } = await verifyRes.json();

Frequently Asked Questions

How many backup codes do I get?

You receive 8 backup codes each time codes are generated or regenerated.

Can I get more codes without invalidating my existing ones?

No. Regenerating codes always replaces the entire set. All previous codes are invalidated and 8 new codes are issued. This is a security measure to prevent accumulation of codes that may have been compromised.

What if I lose all my backup codes and my 2FA device?

If you have lost both your 2FA device and all backup codes, you will need to contact your administrator for an account recovery. An admin can disable 2FA on your account from the Admin Panel → Users page, allowing you to sign in with just your password and re-enable 2FA with a new device.

Do backup codes expire?

No. Backup codes remain valid indefinitely until they are used or you regenerate a new set.

Can I see which codes I have already used?

Your security settings page shows the number of remaining unused codes. Individual used codes are not displayed, since they are stored as irreversible hashes.