Account Security (MFA) API

Manage Multi-Factor Authentication for user accounts. All endpoints require an authenticated session.

Get MFA Status

Check whether MFA is enabled on the current user's account.

GET /api/account/mfa/status

Response:

{
  "mfaEnabled": true,
  "mfaVerifiedAt": "2026-03-22T13:00:00.000Z"
}

Set Up MFA

Generate a new TOTP secret for enrollment. The user must verify the secret with a valid code before MFA becomes active.

POST /api/account/mfa/setup

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth": "otpauth://totp/Veriprompt:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Veriprompt"
}

Use the otpauth URI to generate a QR code for the user to scan with their authenticator app. The secret can be displayed as a manual entry fallback.

WARNING

This endpoint returns the raw TOTP secret. Do not store it client-side or log it.

Verify MFA Setup

Validate the user's first TOTP code to confirm their authenticator is configured correctly. On success, MFA is enabled on the account.

POST /api/account/mfa/verify
Content-Type: application/json

{
  "token": "123456"
}

Success response:

{
  "success": true,
  "mfaEnabled": true
}

Error response (invalid code):

{
  "error": "Invalid MFA token"
}

Disable MFA

Remove MFA from the account. Requires both the current password and a valid TOTP code for security.

POST /api/account/mfa/disable
Content-Type: application/json

{
  "password": "current_password",
  "mfaCode": "123456"
}

Success response:

{
  "success": true,
  "mfaEnabled": false
}

Example: Full MFA Setup Flow

// Step 1: Start setup
const setupRes = await fetch('/api/account/mfa/setup', { method: 'POST' });
const { secret, otpauth } = await setupRes.json();

// Step 2: Display QR code to user (use a QR library with the otpauth URI)
// User scans QR code with authenticator app

// Step 3: Verify with the code from their authenticator
const verifyRes = await fetch('/api/account/mfa/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: userInputCode })
});
const { mfaEnabled } = await verifyRes.json();
// mfaEnabled === true → MFA is now active

Related

• Multi-Factor Authentication Guide — Step-by-step setup instructions
• Authentication — API keys and session tokens
• Security FAQ — Security and compliance questions