Skip to main content

Multi-Factor Authentication (MFA)

This section documents the Multi-Factor Authentication (MFA) API for the BlockBet platform. MFA provides an additional layer of security beyond passwords, requiring users to verify their identity through a second factor.

Overview​

The MFA API allows users to:

  • Set up different types of MFA methods
  • Verify identity using MFA during login and sensitive operations
  • Edit and manage existing MFA settings
  • Configure when MFA is required

Authentication Mechanism​

Authentication is handled automatically via HTTP cookies, with the system managing both accessToken and refreshToken. MFA verification may generate a temporary mfaAccessToken that must be exchanged for a full accessToken through the verification process.

MFA Methods​

The following MFA methods are supported:

  • Authenticator App: Time-based one-time passwords (TOTP) generated by authenticator applications like Google Authenticator
  • Phone: Verification codes sent via SMS to the user's registered phone number

API Operations​

Setup and Management​

  • mfaSetupRequest: Initiates the MFA setup process
  • mfaSetupVerify: Verifies and completes the MFA setup
  • mfaEditRequest: Initiates the process to modify an existing MFA method
  • mfaEditVerify: Verifies and completes the MFA edit
  • disableMfa: Disables MFA for the user
  • editMfaRequirements: Configures when MFA is required (login, withdrawal, device removal)

Verification​

  • mfaRequest: Initiates the MFA verification process during login or sensitive operations
  • mfaVerify: Verifies the MFA code provided by the user

Common Workflow​

  1. Setup: User initiates MFA setup and verifies their ability to receive/generate codes
  2. Usage: During login or sensitive operations, user is prompted for MFA verification
  3. Management: User can edit settings, change MFA type, or disable MFA as needed

Error Handling​

All API operations return standardized responses with appropriate status codes and messages. Common error scenarios include:

  • Invalid verification codes
  • Rate limiting when requesting too many codes
  • Incompatible MFA configurations
  • Unauthorized access attempts

Security Considerations​

  1. MFA verification codes are time-limited
  2. Multiple failed attempts may trigger temporary lockouts
  3. Sensitive operations require recent authentication and verification
  4. Phone numbers and emails are partially masked in responses for privacy