TOTP Setup

Production - POST /api/v1/mfa/totp/enroll, POST /api/v1/mfa/totp/verify, DELETE /api/v1/mfa/totp

TOTP (Time-based One-Time Password) enrollment follows a two-step process: initiation generates a secret and QR code, and verification confirms the user has successfully configured their authenticator app.

6.3.1Enrollment Flow

User                    MfaController              MfaService
  |                           |                          |
  |--- POST /mfa/totp/enroll->|                          |
  |                           |--- initiateTotpEnrollment-->|
  |                           |                          |--- Generate TOTP secret
  |                           |                          |--- Create QR code URI
  |<-- QR code + secret ------|<-- MfaTotpEnrollmentResponse
  |                           |                          |
  |   (User scans QR code)    |                          |
  |                           |                          |
  |--- POST /mfa/totp/verify->|                          |
  |   { code: "123456" }      |--- completeTotpEnrollment-->|
  |                           |                          |--- Verify TOTP code
  |                           |                          |--- Mark as verified
  |                           |                          |--- Generate backup codes
  |<-- backup codes -----------|<-- MfaTotpEnrollmentResponse

Step 1: Initiate Enrollment

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

Response (200 OK)

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUri": "otpauth://totp/MATIH%20Platform:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MATIH%20Platform&algorithm=SHA1&digits=6&period=30",
  "enrolled": false,
  "backupCodes": null
}

Field	Type	Description
`secret`	String	Base32-encoded TOTP secret for manual entry
`qrCodeUri`	String	`otpauth://` URI for QR code generation
`enrolled`	boolean	`false` during initiation, `true` after verification
`backupCodes`	List<String>	Null during initiation, populated after verification

Step 2: Complete Enrollment

curl -X POST http://localhost:8081/api/v1/mfa/totp/verify \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Response (200 OK)

{
  "secret": null,
  "qrCodeUri": null,
  "enrolled": true,
  "backupCodes": [
    "a1b2c3d4", "e5f6g7h8", "i9j0k1l2",
    "m3n4o5p6", "q7r8s9t0", "u1v2w3x4",
    "y5z6a7b8", "c9d0e1f2", "g3h4i5j6",
    "k7l8m9n0"
  ]
}

Backup codes are returned only once during enrollment. Users must save them securely.

6.3.2Disable TOTP

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

Returns 204 No Content on success.

Error Codes

Code	HTTP Status	Description
`MFA_ALREADY_CONFIGURED`	400	TOTP is already enrolled
`MFA_INVALID_CODE`	400	Verification code is incorrect
`MFA_NO_PENDING_ENROLLMENT`	400	No pending TOTP enrollment found
`UNAUTHORIZED`	401	Invalid or missing authentication token

Overview SMS Verification