Skip to main content

Multi-Factor Authentication (MFA)

What it is​

A comprehensive multi-factor authentication system that allows admin and workspace accounts to enable additional authentication layers beyond passwords. The system supports multiple authentication methods and provides backup recovery options.

Who it's for​

Admin
Workspace Owner

Access & Scope​

Admin MFA​

PropertyValue
Moduleadmin-auth
Personasadmin
ScopePlatform-level
UI LocationAdmin Settings > Security
Statusactive

Workspace MFA​

PropertyValue
Moduleworkspace-security
Personasworkspace-owner
ScopeWorkspace-level
UI LocationDashboard > Settings > Security
Statusactive

UI Location​

  • Admin: Admin Settings > Security
  • Workspace: Dashboard > Settings > Security

How it works​

The MFA system provides an additional layer of security by requiring users to provide a second authentication factor beyond their password. This significantly enhances account protection and helps prevent unauthorized access.

Admin MFA​

Admin accounts can enable TOTP (Time-based One-Time Password) authentication:

TOTP Setup​

  1. Generate QR Code: Admin initiates MFA setup
  2. Scan QR Code: Admin scans QR code with authenticator app (Google Authenticator, Authy, Microsoft Authenticator)
  3. Confirm Enrollment: Admin enters a code from the app to confirm setup
  4. MFA Enabled: MFA is now required for admin login

Login Flow with MFA​

  1. Admin enters email and password
  2. System verifies credentials and creates MFA challenge
  3. Admin enters TOTP code from authenticator app
  4. System verifies code and grants access

Workspace MFA​

Workspace owners can enable multiple MFA methods:

Phone OTP (SMS-based)​

  1. Start Enrollment: Enter phone number
  2. Receive OTP: System sends 6-digit code via SMS
  3. Verify Code: Enter code to complete enrollment
  4. Set as Primary (optional): Mark as primary authentication method

TOTP (Authenticator App)​

  1. Generate QR Code: System generates QR code
  2. Scan QR Code: Scan with authenticator app
  3. Confirm Enrollment: Enter code from app to confirm
  4. Set as Primary (optional): Mark as primary authentication method

Backup Codes​

  1. Generate Codes: Create 8-10 recovery codes
  2. Save Securely: Codes shown only once - must be saved
  3. Use for Recovery: Enter code if device is lost
  4. Regenerate: Create new codes (invalidates old unused codes)

Multiple Methods​

  • Multiple MFA methods can be enrolled simultaneously
  • One method can be set as primary
  • Any enrolled method can be used for authentication
  • Methods can be enabled/disabled individually

Security Features​

Encrypted Storage​

  • TOTP secrets are encrypted at rest
  • Phone numbers are stored securely
  • Backup codes are hashed before storage

Challenge-Based Verification​

  • Each login attempt creates a unique challenge
  • Challenges expire after set time (typically 10 minutes)
  • Prevents replay attacks

Attempt Limits​

  • Maximum 5 verification attempts per challenge
  • After 5 failed attempts, new login required
  • Prevents brute force attacks

Replay Protection​

  • TOTP codes can only be used once
  • System tracks last used TOTP code
  • Prevents code reuse attacks

MFA Management​

View Methods​

  • List all enrolled MFA methods
  • See method type (phone_otp, totp)
  • View enrollment date
  • Check primary method status

Set Primary Method​

  • One method can be primary
  • Primary method is preferred for authentication
  • Can change primary method anytime

Enable/Disable Methods​

  • Methods can be disabled (soft delete)
  • Cannot disable if it's the only enabled method
  • Disabled methods cannot be used for authentication

Backup Codes Management​

  • View remaining backup codes count
  • Generate new backup codes
  • Regenerate codes (invalidates old unused codes)
  • Codes shown only once - must be saved securely

Settings​

Admin MFA Settings​

  1. TOTP Setup:

    • Generate QR code
    • Scan with authenticator app
    • Confirm with code

  2. MFA Status:

    • View current MFA status
    • Check if TOTP is enabled

Workspace MFA Settings​

  1. Phone OTP:

    • Enter phone number (E.164 format)
    • Receive and verify OTP code
    • Set as primary (optional)

  2. TOTP:

    • Generate QR code
    • Scan with authenticator app
    • Confirm with code
    • Set as primary (optional)

  3. Backup Codes:

    • Generate 8-10 codes
    • Save codes securely
    • View remaining count
    • Regenerate when needed

  4. Methods Management:

    • View all enrolled methods
    • Set primary method
    • Disable methods

Permissions​

Admin MFA​

  • Admin: Has full access to enable/disable MFA
  • Access: Admin Settings > Security

Workspace MFA​

  • Workspace Owner: Has full access to manage MFA methods
  • Access: Dashboard > Settings > Security

Note: MFA management contains sensitive security information. Access is restricted to account owners only.

Use Cases​

  1. Enhanced Security: Add extra layer of protection to accounts
  2. Compliance: Meet security requirements for sensitive operations
  3. Account Protection: Prevent unauthorized access even if password is compromised
  4. Flexible Authentication: Support different MFA methods based on user preference
  5. Account Recovery: Backup codes provide recovery option if device is lost
  6. Multi-Device Support: Use different methods on different devices

Notes / Limits​

  1. Admin MFA:

    • Only TOTP method supported
    • One TOTP method per admin account
    • MFA is optional but recommended

  2. Workspace MFA:

    • Multiple methods can be enrolled
    • Phone OTP requires verified phone number
    • TOTP requires authenticator app
    • Backup codes are one-time use only

  3. Challenge Expiration:

    • Challenges expire after 10 minutes (default)
    • Must start new login if challenge expires
    • Prevents stale authentication attempts

  4. Attempt Limits:

    • Maximum 5 verification attempts per challenge
    • After 5 failed attempts, must start new login
    • Prevents brute force attacks

  5. Backup Codes:

    • Codes shown only once during generation
    • Must be saved securely (cannot be retrieved)
    • Each code can be used only once
    • Regenerating codes invalidates old unused codes

  6. Primary Method:

    • Only one method can be primary
    • Primary method is preferred but not required
    • Can use any enrolled method for authentication

  7. Method Disabling:

    • Methods can be disabled (soft delete)
    • Cannot disable if it's the only enabled method
    • Disabled methods cannot be used for authentication

  8. Security Best Practices:

    • Enable MFA on all accounts
    • Use authenticator apps (more secure than SMS)
    • Save backup codes in secure location
    • Regenerate backup codes periodically
    • Don't share MFA codes with anyone

Best Practices​

  1. Enable MFA: Enable MFA on all accounts for enhanced security
  2. Use Authenticator Apps: Prefer TOTP over SMS when possible (more secure)
  3. Save Backup Codes: Store backup codes in secure location (password manager, safe)
  4. Multiple Methods: Enroll multiple methods for redundancy
  5. Regular Review: Periodically review enrolled methods
  6. Regenerate Codes: Regenerate backup codes if compromised or lost
  7. Device Security: Keep devices with authenticator apps secure
  8. Don't Share: Never share MFA codes or backup codes with anyone

API Integration​

Admin MFA API​

  • Setup TOTP: POST /api/v1/admin/mfa/totp/setup
  • Confirm TOTP: POST /api/v1/admin/mfa/totp/confirm
  • Verify MFA: POST /api/v1/admin/mfa/verify
  • Get Status: GET /api/v1/admin/mfa/status

Workspace MFA API​

  • Phone OTP Start: POST /api/v1/workspace/mfa/phone/start
  • Phone OTP Verify: POST /api/v1/workspace/mfa/phone/verify
  • TOTP Setup: POST /api/v1/workspace/mfa/totp/setup
  • TOTP Confirm: POST /api/v1/workspace/mfa/totp/confirm
  • Generate Backup Codes: POST /api/v1/workspace/mfa/backup-codes/generate
  • Regenerate Backup Codes: POST /api/v1/workspace/mfa/backup-codes/regenerate
  • Get Backup Codes Count: GET /api/v1/workspace/mfa/backup-codes/count
  • List Methods: GET /api/v1/workspace/mfa/methods
  • Set Primary Method: PATCH /api/v1/workspace/mfa/methods/:methodId/primary
  • Delete Method: DELETE /api/v1/workspace/mfa/methods/:methodId

See Admin MFA API and Workspace MFA API for detailed endpoint documentation.

Changelog​

Recent Updates​

  • Initial release with complete MFA system
  • Admin TOTP support
  • Workspace Phone OTP, TOTP, and Backup Codes support
  • Challenge-based verification
  • Multiple methods management