Set up two-factor authentication (2FA)

Open Settings → Personal → Security → Enable 2FA. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.), enter the 6-digit code, save the backup codes shown once. Strongly recommended for admin and owner roles.

Who is this for

Everyone — but especially admins, owners, super_admins, and finance team members handling billing. 2FA is one of the cheapest, highest-impact security upgrades.

What 2FA gives you

A second factor at login means a stolen password alone can't compromise your account. Even if someone phishes your password, they'd need physical access to your authenticator app to log in. This is critical for:

• Owner accounts (billing access)

• Super admins (cross-org reach)

• Admins of production workspaces

• Anyone with API key creation rights

What you need

• A smartphone (or password manager) with an authenticator app that supports TOTP (Time-based One-Time Password):

  • Google Authenticator (Android / iOS)

  • Authy (multi-device, cloud sync)

  • 1Password / Bitwarden / KeePass (integrated TOTP)

  • Microsoft Authenticator

  • Duo Mobile

• 2-3 minutes to set up

Alternative: email-based OTP (for users without an authenticator app — see below).

How to set up 2FA

Step 1: Open Security settings

Navigate to Settings → Personal → Security (URL: /settings/personal/security).

Step 2: Click Enable 2FA

The page shows your current security status. Click the Enable 2FA button.

Backend calls POST /api/v1/auth/2fa/setup and returns:

• otpauth_url — the standard otpauth:// URI

• qr_code — image (PNG) you scan in your app

• secret — text fallback if you can't scan (paste manually into your app)

Step 3: Scan the QR code

Open your authenticator app:

• Google Authenticator: tap + → Scan QR code

• Authy: tap + → Scan QR code

• 1Password: open item → Add field → One-time password → camera icon

Point the camera at the QR code displayed on the Wevion page. The app adds a "Wevion" entry showing a rotating 6-digit code.

If you can't scan: copy the secret text from below the QR and paste it into your app's "Enter manually" option.

Step 4: Verify the code

Back in Wevion, enter the current 6-digit code from your app. Click Verify.

Backend calls POST /api/v1/auth/2fa/verify. On success, 2FA is enabled.

Step 5: Save backup codes (CRITICAL)

You'll see a list of 10 backup codes. Each is one-time use, for emergency access if you lose your authenticator (lost phone, app reset, etc.).

Save them now:

• Download as text file (button on the page)

• Print and store in a safe place

• Add to your password manager

• Email to yourself (less secure but better than nothing)

You will not see these codes again. Wevion stores hashed versions; we cannot retrieve them if you lose them.

Click I've saved them to finish.

Step 6: Test next login

Log out and log back in. After password, you'll see the 2FA prompt — enter the current 6-digit code from your app.

Email-based OTP alternative

If you don't have an authenticator app, you can use email-based OTP:

• Settings → Personal → Security → Enable email OTP instead of TOTP

• Backend: POST /api/v1/auth/2fa/email-otp to request a code, POST /api/v1/auth/2fa/verify-email-otp to verify

• On each login, after password, Wevion emails a 6-digit code (valid 5 minutes)

Trade-offs:

We strongly recommend TOTP. Email OTP is a fallback.

Using backup codes

If you lose your authenticator:

1. At login, click Use a backup code below the 2FA prompt

2. Enter one of your saved backup codes

3. You're logged in

4. Each code works once — Wevion marks it used

5. Re-set up 2FA immediately on a new device (see Disable + Re-enable below)

Disable 2FA

If you need to disable (changing devices, etc.):

1. Settings → Personal → Security → Disable 2FA

2. Backend: POST /api/v1/auth/2fa/disable

3. Confirm with current password + current 2FA code

4. 2FA is disabled

Important: disabling drops your account back to password-only. Re-enable on the new device immediately if you're moving phones.

Re-enable after device change

If you got a new phone:

1. Disable 2FA on your account using the current device (or a backup code)

2. Enable 2FA on the new device (Step 1-5 above)

3. You get fresh backup codes — save them

Authenticator apps like Authy sync across devices, so you don't need to re-enable just because of a phone upgrade — only when migrating between apps or after a full reset.

What you'll see in the UI

After 2FA is enabled:

• Settings → Personal → Security shows green badge "2FA enabled"

• Active sessions section shows current authenticated sessions

• Login history entries show 2fa_verified: true for successful logins after enabling

• At login: extra step prompting for code

What happens to API keys

API keys are separate from 2FA. Your API keys continue to work regardless. 2FA protects interactive login (browser, app); API keys protect M2M access via the Authorization: Bearer <key> header. Both should be secure for full protection.

Enterprise SSO and 2FA

If your Org uses SSO (SAML / OIDC):

• 2FA is typically handled by your IdP (Okta, Azure AD, etc.), not Wevion directly

• Wevion's 2FA setting may be hidden or shown as "Managed by SSO"

• Talk to your IT admin to configure 2FA at the IdP level

Common issues

• QR code not scanning: too small / glare. Use the manual entry secret instead.

• Code rejected as "invalid": clock skew. Your phone's time must be accurate (within 30 seconds of server time). Enable auto-time-sync on the phone.

• Backup codes lost: regenerate by disabling + re-enabling 2FA (you'll need to authenticate first using current code or a remaining backup).

• Can't disable because no access to authenticator: contact support with verified identity (photo ID, account history) — support can reset 2FA after verification.

• Email OTP not arriving: check spam, whitelist noreply@wevion.ai.

• All backup codes used + no authenticator: contact support to reset.

Best practices

• Enable 2FA on all admin / owner / super_admin accounts

• Store backup codes offline (password manager works; sticky notes don't)

• Use Authy or 1Password for cross-device sync so you don't lose access on phone replacement

• Don't share TOTP codes — they're real-time auth

• Treat 2FA setup as a company policy, not optional, for production workspaces

Related

• Security best practices for your team — broader security checklist

• Personal profile and settings — all personal preferences

• Generate and rotate API keys — companion security topic