MATIH Platform is in active MVP development. Documentation reflects current implementation status.
6. Identity & Access Management
API Reference
MFA Endpoints

MFA Endpoints

The multi-factor authentication endpoints manage TOTP, SMS, and email-based MFA enrollment and verification. All endpoints require an authenticated session. Served by MfaController at /api/v1/mfa.

Endpoints

MethodEndpointDescription
GET/api/v1/mfa/statusGet MFA configuration status
POST/api/v1/mfa/totp/enrollInitiate TOTP enrollment
POST/api/v1/mfa/totp/verifyComplete TOTP enrollment
DELETE/api/v1/mfa/totpDisable TOTP
POST/api/v1/mfa/sms/enrollInitiate SMS enrollment
POST/api/v1/mfa/sms/verifyComplete SMS enrollment
POST/api/v1/mfa/sms/resendResend SMS verification code
DELETE/api/v1/mfa/smsDisable SMS MFA
POST/api/v1/mfa/email/enrollInitiate email MFA enrollment
POST/api/v1/mfa/email/verifyComplete email MFA enrollment
POST/api/v1/mfa/email/resendResend email verification code
DELETE/api/v1/mfa/emailDisable email MFA
POST/api/v1/mfa/backup-codes/regenerateRegenerate backup codes
GET/api/v1/mfa/backup-codes/countGet remaining backup code count

GET /api/v1/mfa/status

Returns the current MFA configuration for the authenticated user, including which methods are enabled and the remaining backup code count.

TOTP Enrollment Flow

  1. Initiate: POST /api/v1/mfa/totp/enroll returns a QR code URI and secret for authenticator app setup
  2. Verify: POST /api/v1/mfa/totp/verify with a valid TOTP code to confirm enrollment
{
  "code": "123456"
}

On successful verification, backup codes are returned. These should be stored securely by the user.

StatusDescription
200Enrollment completed, backup codes returned
400TOTP already configured or invalid code

SMS Enrollment Flow

  1. Initiate: POST /api/v1/mfa/sms/enroll sends a verification code to the provided phone number
{
  "phoneNumber": "+1234567890"
}
  1. Verify: POST /api/v1/mfa/sms/verify with the received code
  2. Resend: POST /api/v1/mfa/sms/resend to request a new code (rate-limited)
StatusDescription
200Code sent or enrollment completed
400Invalid phone number or SMS already configured
429Rate limit exceeded for code resend

Email MFA Enrollment Flow

The email MFA flow mirrors the SMS flow but sends the verification code to the user's registered email address. Uses the same enroll/verify/resend pattern.

Backup Codes

Backup codes are generated during initial MFA enrollment and can be regenerated at any time.

Regenerate (POST /api/v1/mfa/backup-codes/regenerate): Invalidates all existing backup codes and returns a new set.

Count (GET /api/v1/mfa/backup-codes/count): Returns {"remainingCodes": 8}.

Role EndpointsAPI Key Endpoints