Skip to main content
Version: v0.16

Two-Factor Authentication

Two-Factor Authentication (2FA) adds an extra layer of security to user accounts.

Methods​

MethodDescription
Phone OTPOne-time password sent via SMS
QR CodeTOTP via authenticator app

Enable 2FA (Admin)​

  1. Go to Admin Panel > Authentication > Settings
  2. Enable Two-Factor Authentication
  3. Select preferred methods

Enable 2FA

SMS Module Required

Phone-based 2FA requires the SMS module to be configured.

User Flow​

Enable 2FA for Account​

curl -X POST 'http://localhost:3000/authentication/twoFa/enable' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response (QR Code method):

{
  "qrCode": "data:image/png;base64,...",
  "secret": "JBSWY3DPEHPK3PXP"
}

Login with 2FA​

  1. Initial Login:
curl -X POST 'http://localhost:3000/authentication/local' \
  -H 'Content-Type: application/json' \
  -d '{"email": "user@example.com", "password": "password"}'
  1. Response indicates 2FA required:
{
  "message": "2FA required",
  "twoFaRequired": true
}
  1. Submit 2FA code:
curl -X POST 'http://localhost:3000/authentication/twoFa/verify' \
  -H 'Content-Type: application/json' \
  -d '{"code": "123456"}'

Backup Codes​

Generate backup codes for account recovery:

curl -X POST 'http://localhost:3000/authentication/twoFa/backup-codes' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response:

{
  "backupCodes": [
    "ABC12345",
    "DEF67890",
    "GHI11223",
    ...
  ]
}
warning

Backup codes are one-time use. Store them securely.

Disable 2FA​

curl -X POST 'http://localhost:3000/authentication/twoFa/disable' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"code": "123456"}'

Phone OTP Setup​

  1. User must have phone number on account
  2. Enable phone 2FA in settings
  3. OTP sent via configured SMS provider

QR Code Setup​

  1. Enable QR/TOTP in settings
  2. User scans QR code with authenticator app
  3. App generates time-based codes

Supported Apps​

  • Google Authenticator
  • Authy
  • Microsoft Authenticator
  • 1Password
  • Any TOTP-compatible app

Security Best Practices​

  1. Require 2FA for admin accounts
  2. Offer backup codes during setup
  3. Allow multiple methods for flexibility
  4. Log 2FA events for security auditing