--- title: Two-Factor Authentication description: API reference for two-factor authentication (2FA/MFA) readTime: 5 relatedTo: - auth - users - sessions --- # Two-Factor Authentication API Mavibase supports TOTP-based two-factor authentication for enhanced account security. ## Authentication All 2FA endpoints require JWT authentication except for verification during login: ``` Authorization: Bearer your_jwt_token ``` --- ## Setup 2FA Initiates 2FA setup and returns a secret for the authenticator app. ### Endpoint ``` POST /api/v1/platform/2fa/setup ``` ### Example Request ```bash curl -X POST "/api/v1/platform/2fa/setup" \ -H "Authorization: Bearer your_jwt_token" ``` ### JavaScript Example ```javascript const response = await fetch('/api/v1/platform/2fa/setup', { method: 'POST', headers: { Authorization: `Bearer ${token}`, }, }); const { secret, qrCode } = await response.json(); // Display QR code for user to scan console.log('Scan this QR code:', qrCode); ``` ### Response ```json { "success": true, "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "qrCode": "otpauth://totp/Mavibase:user@example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Mavibase", "message": "Scan the QR code with your authenticator app, then verify with a code" } ``` --- ## Verify 2FA Setup Completes 2FA setup by verifying a code from the authenticator app. ### Endpoint ``` POST /api/v1/platform/2fa/setup/verify ``` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `code` | string | Yes | 6-digit code from authenticator app | ### Example Request ```bash curl -X POST "/api/v1/platform/2fa/setup/verify" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your_jwt_token" \ -d '{ "code": "123456" }' ``` ### JavaScript Example ```javascript const response = await fetch( '/api/v1/platform/2fa/setup/verify', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}`, }, body: JSON.stringify({ code: '123456', }), } ); const result = await response.json(); if (result.success) { // Store backup codes securely console.log('Backup codes:', result.backupCodes); } ``` ### Response ```json { "success": true, "message": "Two-factor authentication enabled", "backupCodes": [ "XXXX-XXXX-XXXX", "YYYY-YYYY-YYYY", "ZZZZ-ZZZZ-ZZZZ", "AAAA-AAAA-AAAA", "BBBB-BBBB-BBBB" ] } ``` **Important**: Store backup codes securely. They can be used to access your account if you lose your authenticator device. --- ## Verify 2FA During Login Completes login when 2FA is required. ### Endpoint ``` POST /api/v1/platform/2fa/verify ``` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `tempToken` | string | Yes | Temporary token from login response | | `code` | string | Yes | 6-digit code from authenticator app | ### Example Request ```bash curl -X POST "/api/v1/platform/2fa/verify" \ -H "Content-Type: application/json" \ -d '{ "tempToken": "temp_abc123xyz", "code": "123456" }' ``` ### JavaScript Example ```javascript async function loginWith2FA(email, password) { // Step 1: Initial login const loginResponse = await fetch( '/api/v1/platform/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }), } ); const loginData = await loginResponse.json(); if (loginData.requires2FA) { // Step 2: Prompt user for 2FA code const code = await promptUserForCode(); // Step 3: Verify 2FA const verifyResponse = await fetch( '/api/v1/platform/2fa/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ tempToken: loginData.tempToken, code: code, }), } ); return verifyResponse.json(); } return loginData; } ``` ### Response ```json { "success": true, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "id": "usr_abc123", "email": "user@example.com", "name": "John Doe" } } ``` --- ## Resend 2FA Code Resends the 2FA verification code (for email/SMS-based 2FA). ### Endpoint ``` POST /api/v1/platform/2fa/resend ``` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `tempToken` | string | Yes | Temporary token from login response | ### Example Request ```bash curl -X POST "/api/v1/platform/2fa/resend" \ -H "Content-Type: application/json" \ -d '{ "tempToken": "temp_abc123xyz" }' ``` ### Response ```json { "success": true, "message": "Verification code resent" } ``` --- ## Request 2FA Disable Initiates the process to disable 2FA. ### Endpoint ``` POST /api/v1/platform/2fa/disable ``` ### Example Request ```bash curl -X POST "/api/v1/platform/2fa/disable" \ -H "Authorization: Bearer your_jwt_token" ``` ### Response ```json { "success": true, "message": "Confirm with your authenticator code to disable 2FA" } ``` --- ## Confirm 2FA Disable Completes 2FA disabling by verifying with a code. ### Endpoint ``` POST /api/v1/platform/2fa/disable/confirm ``` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `code` | string | Yes | 6-digit code from authenticator app | ### Example Request ```bash curl -X POST "/api/v1/platform/2fa/disable/confirm" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your_jwt_token" \ -d '{ "code": "123456" }' ``` ### JavaScript Example ```javascript async function disable2FA(code) { // Step 1: Request disable await fetch('/api/v1/platform/2fa/disable', { method: 'POST', headers: { Authorization: `Bearer ${token}` }, }); // Step 2: Confirm with code const response = await fetch( '/api/v1/platform/2fa/disable/confirm', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}`, }, body: JSON.stringify({ code }), } ); return response.json(); } ``` ### Response ```json { "success": true, "message": "Two-factor authentication disabled" } ``` --- ## Supported Authenticator Apps Mavibase 2FA works with any TOTP-compatible authenticator app: - Google Authenticator - Authy - 1Password - Microsoft Authenticator - Bitwarden --- ## Error Responses ### 400 Bad Request ```json { "success": false, "error": { "code": "INVALID_CODE", "message": "Invalid verification code" } } ``` ### 401 Unauthorized ```json { "success": false, "error": { "code": "EXPIRED_TOKEN", "message": "Temporary token has expired. Please login again." } } ``` ### 429 Too Many Requests ```json { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many verification attempts. Please try again later.", "retryAfter": 300 } } ```