Generate Backup Codes

Generate new backup codes and expire old ones.

Endpoint

POST /api/v1/mfa/backup-codes/generate

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>

Validations

• User authentication required
• User must have at least one verified MFA method

Response

Success (200)

{
  "success": true,
  "data": {
    "backup_codes": [
      "ABCD-1234",
      "EFGH-5678",
      "IJKL-9012",
      "..."
    ],
    "total_count": 10,
    "generated_at": "2024-01-01T14:00:00Z"
  },
  "message": "Backup codes generated successfully"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing token
400	NO_MFA_ENABLED	User does not have MFA enabled
500	BACKUP_CODE_GENERATION_ERROR	Internal server error

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. MFA Check

   • Verify user has at least one verified MFA method
   • Return error if MFA not enabled

3. Old Codes Expiration

   • Mark all existing backup codes as expired
   • Set expired_at timestamp

4. New Code Generation

   • Generate 10 new backup codes
   • Format codes (e.g., "ABCD-1234")
   • Hash codes using bcrypt

5. Code Storage

   • Store hashed codes in database
   • Link codes to user
   • Set created_at timestamp

6. Audit Logging

   • Log backup code generation event
   • Record generation timestamp

7. Response

   • Return plain text codes
   • User must save codes securely

Features

• Generates 10 new backup codes
• Expires all existing backup codes
• Returns plain text codes (user should save them securely)
• Each code can only be used once
• Codes are hashed before storage

Important Notes

• Backup codes are shown only once during generation
• User must save codes securely (cannot retrieve them again)
• Old codes are immediately invalidated
• Each backup code can only be used once

Example

curl -X POST https://api.rivergen.com/api/v1/mfa/backup-codes/generate \
  -H "Authorization: Bearer <access_token>"

Related Endpoints

• Get Backup Codes - View masked backup codes
• MFA Status - Check MFA status