Regenerate Recovery Codes

Generates a new set of recovery codes for the authenticated user. All previously issued recovery codes are immediately invalidated. Use this endpoint if recovery codes are lost, compromised, or all have been used.

Request

POST /mfa/recovery-codes/regenerate

Authentication

Requires a valid Bearer JWT token in the Authorization header.

Authorization: Bearer <access_token>

Request Body

No request body required.

Response

Returns an MfaSetupConfirmResponse object containing new one-time recovery codes.

{
  "recoveryCodes": [
    "x9y8z7w6",
    "v5u4t3s2",
    "r1q0p9o8",
    "n7m6l5k4",
    "j3i2h1g0",
    "f9e8d7c6",
    "b5a4z3y2",
    "x1w0v9u8"
  ]
}

Response Fields

Field	Type	Description
recoveryCodes	string[]	Array of new one-time recovery codes. Each code can be used once to log in if the authenticator app is unavailable. Store these securely.

Error Responses

Status Code	Error	Description
401	Unauthorized	Invalid or missing JWT token
404	Not Found	MFA is not enabled for this user

Example

Request

curl -X POST https://api.entryguard.io/api/v1/mfa/recovery-codes/regenerate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "recoveryCodes": [
    "x9y8z7w6",
    "v5u4t3s2",
    "r1q0p9o8",
    "n7m6l5k4",
    "j3i2h1g0",
    "f9e8d7c6",
    "b5a4z3y2",
    "x1w0v9u8"
  ]
}

Important Notes

• MFA must already be enabled to use this endpoint
• All previous recovery codes are immediately invalidated
• The new codes are the only valid recovery codes for this user
• Each code can only be used once
• Store these codes securely (password manager, encrypted file, printed and stored safely)
• This action is logged in the audit trail
• Recovery codes are case-insensitive

Use Cases

• User has lost their recovery codes
• User has used most/all of their recovery codes
• Security concern that recovery codes may have been compromised
• Regular security maintenance (rotating recovery codes)