Multi-Factor Authentication Overview

Production - MfaController, MfaPolicyController, MfaRecoveryController

The MATIH platform supports three MFA methods (TOTP, SMS, Email) plus backup codes. MFA can be enforced through per-tenant policies that apply based on user roles, risk scores, or contextual signals like new devices or IP addresses.

Supported MFA Methods

Method	Type	Description	Sprint
TOTP	Time-based One-Time Password	RFC 6238 compatible authenticator apps	CP-001
SMS	SMS Verification	Code sent via Twilio to registered phone	CP-003
Email	Email Verification	Code sent to user's registered email	Sprint 2
Backup Codes	One-time codes	10 codes generated during enrollment	CP-005

MFA Status Endpoint

Check the current MFA configuration for the authenticated user:

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

Response

{
  "mfaEnabled": true,
  "totpEnabled": true,
  "smsEnabled": false,
  "emailEnabled": true,
  "remainingBackupCodes": 8,
  "preferredMethod": "TOTP",
  "enrolledMethods": ["TOTP", "EMAIL"]
}

Section Pages

Page	Description
TOTP Setup	QR code generation, authenticator app enrollment, verification
SMS Verification	Phone number enrollment, SMS code delivery and verification
Email MFA	Email-based MFA enrollment and verification
Backup Codes	Generation, usage, and regeneration of backup codes
MFA Policies	Per-tenant enforcement rules, conditional MFA
MFA Recovery	Self-service and admin recovery flows

Multi-Factor Authentication TOTP Setup