Backup Codes

Backup codes are one-time use codes generated during MFA enrollment. They serve as a fallback when the primary MFA method is unavailable (lost phone, no email access).

Backup codes are automatically generated when any MFA method is enrolled. The default configuration generates 10 codes.

Regenerate Backup Codes

Regeneration invalidates all existing backup codes and creates a new set:

curl -X POST http://localhost:8081/api/v1/mfa/backup-codes/regenerate \
  -H "Authorization: Bearer <access-token>"

Response (200 OK)

{
  "backupCodes": [
    "a1b2c3d4", "e5f6g7h8", "i9j0k1l2",
    "m3n4o5p6", "q7r8s9t0", "u1v2w3x4",
    "y5z6a7b8", "c9d0e1f2", "g3h4i5j6",
    "k7l8m9n0"
  ]
}

Check Remaining Count

curl -X GET http://localhost:8081/api/v1/mfa/backup-codes/count \
  -H "Authorization: Bearer <access-token>"

Response (200 OK)

{
  "remainingCodes": 8
}

During login MFA verification, backup codes can be used instead of TOTP or SMS codes:

curl -X POST http://localhost:8081/api/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": "a1b2c3d4",
    "codeType": "BACKUP_CODE"
  }'

Each backup code can only be used once. After use, it is marked as consumed in the database.

Security Notes

• Backup codes are hashed before storage -- they cannot be retrieved after initial display
• Users should be alerted when remaining backup codes fall below a threshold (e.g., 3)
• Regeneration is audited and requires an authenticated session
• MFA must be enabled to regenerate backup codes

Error Codes