MFA Recovery

MFA recovery provides escape paths when users lose access to their MFA devices. The service supports two recovery flows: self-service recovery via email and admin-initiated MFA reset.

Initiate Recovery

curl -X POST http://localhost:8081/api/v1/mfa/recovery/initiate \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

Response (200 OK)

The response always indicates success to prevent email enumeration:

{
  "message": "If an account exists with MFA enabled, a recovery link has been sent.",
  "success": true
}

Verify Recovery Token

curl -X POST http://localhost:8081/api/v1/mfa/recovery/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "recovery-token-from-email",
    "email": "user@example.com"
  }'

On success, all MFA methods are disabled for the user, allowing them to log in with just their password and re-enroll MFA.

Administrators can reset MFA for users who cannot perform self-service recovery.

Admin Reset

curl -X POST http://localhost:8081/api/v1/mfa/recovery/admin/reset \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "userId": 42,
    "reason": "User lost access to authenticator app - ticket INC-12345"
  }'

Requirements

• Requires ADMIN role or mfa:reset permission
• The reason field is mandatory and recorded in audit logs
• An email notification is sent to the user informing them of the reset

Check Recovery Status

curl -X GET http://localhost:8081/api/v1/mfa/recovery/admin/status/42 \
  -H "Authorization: Bearer <admin-token>"

Security Considerations

• Recovery initiation is rate-limited to prevent abuse
• Recovery tokens have a limited validity period
• Admin resets require a documented reason for compliance
• All recovery events are recorded in the audit log
• The response to recovery initiation never reveals whether the email exists (anti-enumeration)

Error Codes