# Authentication & 2FA

## Overview

WaDesk signs users in with a standard, secure session login for the web app. It covers everything you'd expect — login, registration, logout, and password reset — plus the steps that create or switch a workspace after you sign in. On top of that, WaDesk adds two-factor authentication (2FA) with an authenticator app, an admin policy to require 2FA, and a show/hide toggle on every password field.

Passwords are stored using bcrypt, a strong one-way hash — they're never kept in readable form and are never sent back out by the app.

## Registration Flow

Sign-up is a guided, multi-step flow so a new operator never lands on an empty dashboard. The account is created first, then the user is walked through creating a workspace and (optionally) picking a plan.

1. Step 1 — Account. Name, email, password (at least 8 characters, entered twice to confirm), and an accepted Terms checkbox. The email must not already be in use. If an administrator has turned on Auto-verify email (under Admin → Settings → General), the account is verified right away; otherwise the user goes through the usual verify-your-email screen.
2. Step 2 — Workspace. The new user names their first workspace. It starts on the default plan the administrator chose, and if that's a free plan the trial countdown begins.
3. Step 3 — Plan / credits. An optional step to buy a credit pack — you can skip it and come back from your wallet later.

Referrals are tracked during sign-up: if someone arrives through a referral link, the referrer gets the credit. You can't refer yourself, and a referral can't be counted twice.

> Note: Platform staff (Super Admin, Admin, Platform Support, Auditor) skip the workspace step entirely. On login they go straight to the admin area, since workspaces are a customer-side concept.

## Login & Logout

Login checks the email and password. On success, the session is refreshed to a new ID (which prevents session-fixation attacks), and the user is sent to the right place for their role:

- Platform staff → the admin panel.
- A user with no workspace → the workspace-creation step.
- Agents / Viewers → the Team Inbox (their home — they don't have dashboard access).
- Everyone else → the dashboard (or wherever they were originally headed).

A Remember me option keeps you signed in across browser sessions. Logging out ends the session completely, so the old session can never be reused.

> Failed-login messages are deliberately vague. A wrong email and a wrong password both show the same "credentials don't match" message, so the form never reveals whether an email is registered.

## Password Reset

The forgot-password flow always replies with the same neutral message — "A password-reset link has been sent if that email exists" — whether or not the email is on file, so it can't be used to discover which emails have accounts. The reset link works only once and expires after a while; using it sets a new password (stored securely) and sends the user back to login.

> Before going live: A fresh install may be set up to write emails into a log file instead of actually sending them — which means reset links would land in a log instead of reaching users. Configure a real email service so reset links are delivered properly and aren't sitting in a log file.

## Two-Factor Authentication (TOTP)

WaDesk has its own built-in two-factor system based on the standard TOTP method (RFC 6238) — the same approach used by every popular authenticator app, so Google Authenticator, 1Password, Authy, and similar all work. It shows a QR code to scan, then verifies the 6-digit codes your app generates (which change every 30 seconds). It allows one code's worth of clock drift on either side, so you're not locked out if your phone's clock is slightly off.

Users turn on 2FA from Settings → Security:

- Enable — the app shows the QR code; you confirm by entering a current code. 2FA is only switched on once a code verifies successfully.
- Disable — you must re-enter your account password before 2FA is turned off and the stored secret and recovery codes are erased.

Every enable, disable, and failed attempt is recorded in the security audit log, along with who did it, the workspace, the IP address, and the browser.

### How 2FA Data Is Stored

The two sensitive pieces — the authenticator secret and your recovery codes — are always stored encrypted, never in readable form:

What's stored | Protection
--- | ---
Whether 2FA is on | Plain on/off flag
The authenticator secret (used to check your codes) | Encrypted
Your one-time recovery codes | Encrypted
When 2FA was confirmed | Plain date/time

## Enforced 2FA (Admin Policy)

Platform owners can require 2FA from Admin → Security. Any user covered by the policy who hasn't set up 2FA yet is sent to the security settings screen to do so before they can continue. There are three switches:

Policy | Who it requires 2FA from
--- | ---
Require 2FA for everyone | Every signed-in user
Require 2FA for admins | Users with an admin-level role
Require 2FA for owners | Anyone who owns at least one workspace

The login, logout, registration, password, email-verification, and 2FA-setup screens always stay reachable, so a user can always get to the screen where they enroll. The admin Security dashboard also shows a live 2FA coverage figure — the percentage of admin users who have confirmed 2FA.

> Recommended: For any live deployment, turn on Require 2FA for admins (and ideally for owners) under Admin → Security. Admin and owner accounts can reach billing, message sending, and other workspaces' data — they're the highest-value targets and shouldn't rely on a password alone.

## Session Management

Sessions are tracked on the server. Beyond login and logout, WaDesk lets operators and admins control active sessions directly:

- Per-user (Settings → Security): sign out an individual device, or "revoke all other sessions" to sign out every device except the one you're on. You can't sign out your current session here — use Logout for that.
- Platform-wide (Admin → Security, Super Admin only): a single "revoke all sessions" action signs out every user everywhere and forces them all to log in again.

Related platform policies — session timeout, maximum number of devices signed in at once, locking an account after repeated failed logins, and whether "Remember me" is offered — are all set on the Admin → Security page.

## Universal Password Reveal

Every password field in the app automatically gets a show/hide eye button — the login and register forms, the security tab, admin payment-gateway credential fields, and the API-key inputs all get it, including fields that appear later as you expand a section. The reveal happens entirely in your browser; the value is never sent anywhere or written to a log.

Template authors can also force the eye button onto a non-password field by adding `data-reveal`, or hide it from a field with `data-no-reveal`.