MFA Reference

Multi-Factor Authentication (TOTP) configuration.

Overview

MFA is automatically enabled when Supabase and JWT are configured. Uses RFC 6238 TOTP standard.

Endpoints

Method	Endpoint	Description
POST	/mfa/setup	Generate TOTP secret & QR
POST	/mfa/verify	Verify TOTP code
POST	/mfa/enable	Enable MFA for user
POST	/mfa/disable	Disable MFA for user
GET	/mfa/status	Get MFA status
GET	/mfa/backup-codes	Generate backup codes
POST	/mfa/backup-codes/verify	Verify backup code

Setup Flow

1. Initialize Setup

POST /mfa/setup
Authorization: Bearer <token>

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,...",
  "manualEntry": "JBSWY3DPEHPK3PXP"
}

2. Verify Code

POST /mfa/verify
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "123456"
}

Response:

{
  "valid": true
}

3. Enable MFA

POST /mfa/enable
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "123456"
}

Response:

{
  "enabled": true,
  "backupCodes": [
    "abc123def456",
    "ghi789jkl012",
    ...
  ]
}

Backup Codes

Generate New Codes

GET /mfa/backup-codes
Authorization: Bearer <token>

Returns 10 single-use recovery codes.

Use Backup Code

POST /mfa/backup-codes/verify
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "abc123def456"
}

MFA Status

GET /mfa/status
Authorization: Bearer <token>

Response:

{
  "enabled": true,
  "backupCodesRemaining": 8
}

Disable MFA

POST /mfa/disable
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "123456"
}

Database Schema

CREATE TABLE user_mfa (
  user_id TEXT PRIMARY KEY,
  secret TEXT NOT NULL,
  enabled BOOLEAN DEFAULT FALSE,
  backup_codes TEXT[],
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Auth with MFA

Login Flow

1. User logs in with credentials
2. Server returns partial token or MFA required flag
3. Client prompts for TOTP code
4. Submit code to /auth/mfa/verify
5. Server returns full JWT

Auth Endpoints

Method	Endpoint	Description
POST	/auth/login	Initial login
POST	/auth/mfa/verify	Complete MFA login

Security

• Secrets stored encrypted
• Backup codes hashed with SHA-256
• Codes valid for 30-second windows
• Rate limited to prevent brute force
• Audit logging for all MFA events