TOTP-based 2FA with backup codes. Works with any authenticator app — Google Authenticator, Authy, 1Password.

Two-Factor Authentication

FastCMS supports TOTP-based two-factor authentication for enhanced account security.

Features

TOTP-based — Time-based One-Time Passwords (RFC 6238)
QR Code Setup — easy scanning with authenticator apps
Backup Codes — 10 one-time recovery codes
Secure Storage — secrets stored securely in the database

Setup 2FA

Step 1: Generate Setup

curl -X POST http://localhost:8000/api/v1/auth/2fa/setup \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...",
  "otpauth_url": "otpauth://totp/FastCMS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=FastCMS"
}

Step 2: Scan QR Code

Open your authenticator app (Google Authenticator, Authy, 1Password, etc.) and scan the QR code.

Step 3: Enable 2FA

curl -X POST http://localhost:8000/api/v1/auth/2fa/enable \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Response:

{
  "enabled": true,
  "backup_codes": [
    "a1b2-c3d4",
    "e5f6-g7h8",
    "i9j0-k1l2",
    "m3n4-o5p6",
    "q7r8-s9t0",
    "u1v2-w3x4",
    "y5z6-a7b8",
    "c9d0-e1f2",
    "g3h4-i5j6",
    "k7l8-m9n0"
  ],
  "message": "2FA enabled successfully. Save your backup codes securely."
}

Important: Save your backup codes in a secure location. Each code can only be used once.

First Request (Password Only)

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

Response (2FA Required):

{
  "user": {"id": "...", "two_factor_enabled": true},
  "token": {"access_token": "", "expires_in": 0},
  "requires_2fa": true,
  "message": "Two-factor authentication required"
}

Second Request (With 2FA Code)

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "yourpassword",
    "two_factor_code": "123456"
  }'

Using Backup Codes

Use a backup code in place of the TOTP code:

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "yourpassword",
    "two_factor_code": "a1b2-c3d4"
  }'

Each backup code can only be used once and is automatically invalidated after use.

API Reference

Endpoint	Method	Description
`/api/v1/auth/2fa/status`	GET	Check 2FA status
`/api/v1/auth/2fa/setup`	POST	Generate setup (secret + QR code)
`/api/v1/auth/2fa/enable`	POST	Enable 2FA with verification code
`/api/v1/auth/2fa/disable`	POST	Disable 2FA
`/api/v1/auth/2fa/backup-codes`	POST	Regenerate backup codes

Disable 2FA

curl -X POST http://localhost:8000/api/v1/auth/2fa/disable \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Troubleshooting

Issue	Solution
Code invalid	Ensure device time is synced (TOTP is time-based)
QR code won't scan	Use the manual entry secret instead
Lost authenticator	Use a backup code to log in, then disable 2FA
No backup codes left	Contact administrator to reset 2FA

Two-Factor Authentication

On this page