Get Backup Codes

Get masked backup codes for the current user (for display purposes only).

Quick Navigation

• Endpoint
• Headers
• Response
• Success (200)
• Error Codes
• Data Flow
• Features
• Important Notes
• Example
• Related Endpoints

Endpoint

GET /api/v1/mfa/backup-codes

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>

Response

Success (200)

{
  "success": true,
  "data": {
    "backup_codes": [
      {
        "id": 1,
        "masked_code": "AB****CD",
        "used": false,
        "created_at": "2024-01-01T14:00:00Z",
        "expires_at": null
      },
      {
        "id": 2,
        "masked_code": "EF****GH",
        "used": true,
        "created_at": "2024-01-01T14:00:00Z",
        "expires_at": null
      }
    ],
    "total_count": 10,
    "unused_count": 9
  },
  "message": "Backup codes retrieved successfully"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing token
500	BACKUP_CODE_RETRIEVAL_ERROR	Internal server error

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Backup Codes Query

   • Query BackupCode table
   • Filter by user ID
   • Filter by expired_at IS NULL
   • Order by created_at DESC

3. Code Masking

   • Mask each code (show first 2 and last 2 characters)
   • Hide middle characters for security
   • Only show unused codes if specified

4. Data Formatting

   • Format code details
   • Include usage status
   • Include timestamps

5. Response

   • Return masked codes
   • Return total and unused counts

Features

• Returns masked backup codes (e.g., "AB****CD")
• Only shows unused backup codes (by default)
• Safe for display in UI
• Cannot be used to authenticate (masked)
• Shows usage status

Important Notes

• Codes are masked for security
• Masked codes cannot be used for authentication
• Only unused codes are shown by default
• User must use Generate Backup Codes to get new codes

Example

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

Related Endpoints

• Generate Backup Codes - Generate new backup codes
• MFA Status - Check backup codes count