Two-Factor Authentication API

Secure your users' accounts with two-factor authentication (2FA). BRDZ supports TOTP-based 2FA using authenticator apps like Google Authenticator, Authy, or 1Password. Includes comprehensive audit logging via user_2fa_logs table.

Setup 2FA

POST/api/2fa/setup

Setup 2FA

Generate secret and QR code for 2FA setup. Creates or updates user_2fa_settings record with is_enabled=FALSE. Generates 8 backup codes. User scans QR code with authenticator app.

Request Body

{}

Response

2002FA setup data generated successfully

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "backup_codes": [
      "A1B2C3D4",
      "E5F6G7H8",
      "I9J0K1L2",
      "M3N4O5P6",
      "Q7R8S9T0",
      "U1V2W3X4",
      "Y5Z6A7B8",
      "C9D0E1F2"
    ],
    "manual_entry_key": "JBSWY3DPEHPK3PXP",
    "issuer": "BRDZ SDK Dashboard",
    "account_name": "user@example.com"
  }
}

4002FA already enabled

{
  "success": false,
  "error": "2FA is already enabled. Disable it first to setup again."
}

curl -X POST https://api.brdz.link/api/2fa/setup \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Enable 2FA

POST/api/2fa/enable

Enable 2FA

Enable 2FA after user has scanned QR code. Verifies TOTP token from authenticator app and sets is_enabled=TRUE in user_2fa_settings. Updates setup_completed_at timestamp.

Parameters

tokenstringrequired

6-digit verification code from authenticator app

Request Body

{
  "token": "123456"
}

Response

2002FA enabled successfully

{
  "success": true,
  "message": "2FA enabled successfully"
}

400Invalid request or already enabled

{
  "success": false,
  "error": "2FA not setup. Please setup 2FA first."
}

401Invalid verification token

{
  "success": false,
  "error": "Invalid verification code"
}

curl -X POST https://api.brdz.link/api/2fa/enable \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"token": "123456"}'

Get 2FA Status

GET/api/2fa/status

Get 2FA Status

Check 2FA status for current user from user_2fa_settings table. Returns setup and enablement status with timestamps and backup codes count.

Response

2002FA status retrieved successfully

{
  "success": true,
  "data": {
    "is_enabled": true,
    "is_setup": true,
    "setup_completed_at": "2024-01-15T10:30:00Z",
    "last_used_at": "2024-01-15T12:45:00Z",
    "backup_codes_count": 8
  }
}

200_not_setup2FA not setup

{
  "success": true,
  "data": {
    "is_enabled": false,
    "is_setup": false,
    "setup_completed_at": null,
    "last_used_at": null,
    "backup_codes_count": 0
  }
}

curl -X GET https://api.brdz.link/api/2fa/status \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Disable 2FA

POST/api/2fa/disable

Disable 2FA

Disable 2FA for current user. Requires both current 2FA token and password verification using bcryptjs. Sets is_enabled=FALSE in user_2fa_settings (keeps record for audit).

Parameters

tokenstringrequired

6-digit verification code from authenticator app

passwordstringrequired

User's current password for security verification

Request Body

{
  "token": "123456",
  "password": "currentPassword123"
}

Response

2002FA disabled successfully

{
  "success": true,
  "message": "2FA disabled successfully"
}

400Missing required fields or 2FA not enabled

{
  "success": false,
  "error": "Both verification token and password are required"
}

401Invalid credentials

{
  "success": false,
  "error": "Invalid password"
}

curl -X POST https://api.brdz.link/api/2fa/disable \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "token": "123456",
  "password": "currentPassword123"
}'

Get Backup Codes

POST/api/2fa/backup-codes

Get Backup Codes

Retrieve backup codes for 2FA. Requires password verification using bcryptjs for security. Returns backup_codes array from user_2fa_settings table.

Parameters

passwordstringrequired

User's current password for security verification

Request Body

{
  "password": "currentPassword123"
}

Response

200Backup codes retrieved successfully

{
  "success": true,
  "data": {
    "backup_codes": [
      "A1B2C3D4",
      "E5F6G7H8",
      "I9J0K1L2",
      "M3N4O5P6",
      "Q7R8S9T0",
      "U1V2W3X4",
      "Y5Z6A7B8",
      "C9D0E1F2"
    ]
  }
}

400Missing password or 2FA not enabled

{
  "success": false,
  "error": "Password is required to view backup codes"
}

401Invalid password

{
  "success": false,
  "error": "Invalid password"
}

curl -X POST https://api.brdz.link/api/2fa/backup-codes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"password": "currentPassword123"}'

POST/api/2fa/verify-login

Verify 2FA for Login

Verify 2FA token during login process. No authentication required. Updates last_used_at timestamp in user_2fa_settings. Used with /auth/complete-login endpoint.

Parameters

user_idnumberrequired

User ID from initial login response

tokenstringrequired

6-digit verification code from authenticator app

Request Body

{
  "user_id": 123,
  "token": "123456"
}

Response

2002FA verification successful

{
  "success": true,
  "message": "2FA verification successful"
}

400Missing required fields or 2FA not enabled

{
  "success": false,
  "error": "User ID and verification token are required"
}

401Invalid verification token

{
  "success": false,
  "error": "Invalid verification code"
}

curl -X POST https://api.brdz.link/api/2fa/verify-login \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "user_id": 123,
  "token": "123456"
}'

Database Schema

Based on controller implementation, the following tables are used:

user_2fa_settings Table

- user_id (reference to users table)
- totp_secret (encrypted TOTP secret)
- backup_codes (array of 8 backup codes)
- is_enabled (boolean)
- setup_completed_at (timestamp)
- last_used_at (timestamp)
- created_at, updated_at (timestamps)

user_2fa_logs Table (Audit Trail)

- user_id (reference to users table)
- action (setup, enabled, disabled, verified, failed_verification, etc.)
- ip_address (client IP)
- user_agent (client browser/app)
- success (boolean)
- failure_reason (text, nullable)
- created_at (timestamp)

2FA Workflow

Setup Flow

Setup: Call /2fa/setup to get QR code and backup codes
Scan: User scans QR code with authenticator app (Google Authenticator, Authy, etc.)
Enable: Call /2fa/enable with verification token to activate 2FA
Store: Securely save backup codes

Login: Call /auth/login with username/password
Check: If response has requires_2fa: true
Verify: Call /2fa/verify-login with user_id and 2FA token
Complete: Call /auth/complete-login to get JWT token

Security Features

Based on controller implementation:

Password Verification: Required for disable and backup codes access
Audit Logging: All 2FA activities logged to user_2fa_logs table
IP Tracking: Client IP and User-Agent logged for security monitoring
Token Window: 2-step time tolerance for TOTP verification
Backup Codes: 8 backup codes generated (8 chars each, hex uppercase)
Database Persistence: Settings kept for audit even when disabled

Error Handling

The controller logs all 2FA activities including failures:

// Failed verification logging
await log2FAActivity(user_id, 'failed_verification', false, 'Invalid token during enable', req);

// Successful operations logging  
await log2FAActivity(user_id, 'enabled', true, null, req);

Supported Authenticator Apps

Based on TOTP standard (RFC 6238):

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

Security Requirements

Password verification required for sensitive operations
All activities logged for audit trail
Backup codes should be stored securely offline
Each backup code can only be used once

Implementation Notes

Uses speakeasy library for TOTP generation/verification
QR codes generated using qrcode library
Password hashing verified with bcryptjs
Database transactions ensure data consistency

Setup 2FA​

Setup 2FA

Request Body

Response

Enable 2FA​

Enable 2FA

Parameters

Request Body

Response

Get 2FA Status​

Get 2FA Status

Response

Disable 2FA​

Disable 2FA

Parameters

Request Body

Response

Get Backup Codes​

Get Backup Codes

Parameters

Request Body

Response

Verify 2FA for Login​

Verify 2FA for Login

Parameters

Request Body

Response

Database Schema​

user_2fa_settings Table​

user_2fa_logs Table (Audit Trail)​

2FA Workflow​

Setup Flow​

Login Flow​

Security Features​

Error Handling​

Setup 2FA

Enable 2FA

Get 2FA Status

Disable 2FA

Get Backup Codes

Verify 2FA for Login

Database Schema

user_2fa_settings Table

user_2fa_logs Table (Audit Trail)

2FA Workflow

Setup Flow

Login Flow

Security Features

Error Handling