Skip to main content

Two-Factor Authentication

TOTP-based MFA adds a second factor to user accounts. After entering their password, users must provide a time-based code from their authenticator app.

Enrolling​

POST /v1/auth/mfa/enroll
Authorization: Bearer <token>

Response includes a QR code URI for the authenticator app:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUri": "otpauth://totp/WardenAuth:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WardenAuth",
  "backupCodes": ["abcd-efgh-ijkl", "mnop-qrst-uvwx", ...]
}

Verifying Setup​

After scanning the QR code, verify that the codes sync:

POST /v1/auth/mfa/verify
Authorization: Bearer <token>

{ "code": "123456" }

MFA is activated on success. Store the backup codes — each can be used once to bypass MFA if you lose your authenticator device.

Backup Codes​

Ten single-use codes are generated at enrollment. Use one to recover access:

POST /v1/auth/mfa/recover
{ "email": "admin@example.com", "backupCode": "abcd-efgh-ijkl" }

Each code works once. After all ten are consumed, re-enroll to generate new ones.

Disabling​

DELETE /v1/auth/mfa
Authorization: Bearer <token>

Disables MFA and invalidates all backup codes.