Multi-factor authentication (MFA) adds a second verification step to your VeriSwarm account. With MFA enabled, logging in requires both your password and a time-based one-time password (TOTP) from an authenticator app.
Several VeriSwarm operations require MFA verification:
Without MFA, these operations are blocked. Even if your password is compromised, MFA prevents an attacker from performing destructive actions.
You need a TOTP authenticator app. Any app that supports the TOTP standard works:
Navigate to Account > Settings > Security and click Enable MFA.
curl -X POST https://veriswarm.ai/v1/public/accounts/mfa/setup \
-H "x-account-access-token: YOUR_SESSION_TOKEN"
Response:
{
"status": "mfa_secret_issued",
"account_id": "usr_abc123",
"mfa_enabled": false,
"totp_secret": "JBSWY3DPEHPK3PXP",
"otpauth_url": "otpauth://totp/VeriSwarm:you@example.com?secret=JBSWY3DPEHPK3PXP&issuer=VeriSwarm"
}
The totp_secret is only shown once during initial setup. If you call this endpoint again before enabling MFA, it returns the otpauth_url (for the QR code) but not the raw secret.
totp_secret string into your authenticator app. Use "VeriSwarm" as the issuer and your email as the account name.Your authenticator app will now show a 6-digit code that changes every 30 seconds.
Enter the current 6-digit code from your authenticator app to confirm setup.
Enter the code in the verification field and click Verify.
curl -X POST https://veriswarm.ai/v1/public/accounts/mfa/enable \
-H "x-account-access-token: YOUR_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mfa_code": "123456"
}'
Response (includes recovery codes -- save these immediately):
{
"status": "enabled",
"account_id": "usr_abc123",
"mfa_enabled": true,
"mfa_recovery_codes": [
"abc12-def34",
"ghi56-jkl78",
"mno90-pqr12",
"stu34-vwx56",
"yza78-bcd90",
"efg12-hij34",
"klm56-nop78",
"qrs90-tuv12",
"wxy34-zab56",
"cde78-fgh90"
]
}
You receive 10 recovery codes when MFA is enabled. Each code can be used exactly once to log in if you lose access to your authenticator device.
Store these securely:
If you use all recovery codes or suspect they have been compromised, regenerate them (requires a valid MFA code):
curl -X POST https://veriswarm.ai/v1/public/accounts/mfa/recovery-codes/regenerate \
-H "x-account-access-token: YOUR_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mfa_code": "123456"
}'
This invalidates all previous recovery codes and issues 10 new ones.
If you lose access to your authenticator device, use a recovery code in place of the MFA code during login. Each recovery code works exactly once -- after use, it is permanently consumed.
If you run out of recovery codes and cannot access your authenticator, contact your workspace owner or admin for assistance.
To disable MFA, you must provide your email, password, and either a valid MFA code or a recovery code. This prevents an attacker with only session access from disabling MFA.
curl -X POST https://veriswarm.ai/v1/public/accounts/mfa/disable \
-H "x-account-access-token: YOUR_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "you@example.com",
"password": "your-password",
"mfa_code": "123456"
}'
Or using a recovery code:
{
"email": "you@example.com",
"password": "your-password",
"recovery_code": "abc12-def34"
}
After disabling, the MFA secret and all recovery codes are permanently deleted. You can re-enable MFA at any time by starting the setup flow again.
When you switch to a different workspace, your MFA verification is cleared for the current session. This is intentional -- each workspace is a separate security boundary. You will be prompted to re-verify MFA the next time you attempt a sensitive operation in the new workspace.