Two-Factor Authentication (2FA)

Two-Factor Authentication adds an extra layer of security to user accounts by requiring a time-based one-time password (TOTP) in addition to the regular password.

Overview

AutoCom uses the industry-standard TOTP algorithm, compatible with popular authenticator apps like:

• Google Authenticator
• Microsoft Authenticator
• Authy
• 1Password
• Bitwarden

API Endpoints

All 2FA endpoints require authentication via Bearer token.

Check 2FA Status

GET /api/v1/2fa/status

Response:

{
  "enabled": false,
  "confirmed": false,
  "backup_codes_remaining": 0
}

Enable 2FA (Step 1)

Generate a secret and QR code for the authenticator app.

POST /api/v1/2fa/enable
Content-Type: application/json

{
  "password": "your-current-password"
}

Response:

{
  "secret": "5RLBRQ3HY6BRZDDKPVPGZADXW5JMMJEK",
  "qr_code_url": "otpauth://totp/AutoStore:user@example.com?secret=...",
  "message": "Scan the QR code with your authenticator app, then confirm with a code."
}

Confirm 2FA (Step 2)

Verify setup by providing a valid TOTP code from your authenticator app.

POST /api/v1/2fa/confirm
Content-Type: application/json

{
  "code": "123456"
}

Response:

{
  "message": "Two-factor authentication has been enabled.",
  "backup_codes": [
    "ABCD-EFGH",
    "IJKL-MNOP",
    "..."
  ],
  "warning": "Store these backup codes in a secure location. They can only be used once."
}

Disable 2FA

POST /api/v1/2fa/disable
Content-Type: application/json

{
  "password": "your-current-password",
  "code": "123456"
}

The code can be either a 6-digit TOTP code or a backup code.

Response:

{
  "message": "Two-factor authentication has been disabled."
}

Regenerate Backup Codes

Generate new backup codes, invalidating all previous ones.

POST /api/v1/2fa/regenerate-backup-codes
Content-Type: application/json

{
  "password": "your-current-password"
}

Response:

{
  "message": "New backup codes have been generated.",
  "backup_codes": [
    "WXYZ-1234",
    "..."
  ],
  "warning": "Your previous backup codes are no longer valid."
}

Login Flow with 2FA

When a user with 2FA enabled attempts to login:

Step 1: Initial Login

POST /api/v1/auth/login
X-Tenant: your-tenant
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response (2FA Required):

{
  "message": "Two-factor authentication required",
  "requires_2fa": true,
  "user_id": 123,
  "two_factor_token": "random-temporary-token"
}

Step 2: Verify 2FA Code

POST /api/v1/auth/2fa/verify
X-Tenant: your-tenant
Content-Type: application/json

{
  "user_id": 123,
  "code": "123456",
  "two_factor_token": "random-temporary-token"
}

Response:

{
  "message": "Two-factor authentication verified.",
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "user@example.com"
  },
  "role": "admin",
  "permissions": ["..."],
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_at": "2026-01-11T21:00:00Z"
}

Backup Codes

Backup codes are 8-character codes in the format XXXX-XXXX. They are:

• Generated when 2FA is first enabled
• Single-use (each code can only be used once)
• Can be regenerated at any time (invalidates old codes)
• Useful for account recovery if authenticator app is unavailable

Best Practices:

• Store backup codes in a secure location (password manager, safe deposit box)
• Never share backup codes with anyone
• Regenerate codes if you suspect they've been compromised
• Keep track of how many codes remain

Security Considerations

1. Password Verification: All sensitive 2FA operations require current password
2. Rate Limiting: Failed 2FA attempts are logged and rate-limited
3. Token Expiry: The temporary 2FA token expires after 10 minutes
4. Encrypted Storage: TOTP secrets and backup codes are encrypted at rest