Authentication — User Guide

Tenant Application

Register

1. Open /register.
2. If registration is closed, you will see: We are not currently accepting new registrations.
3. Otherwise enter company name, your name, work email, and password.
4. After success you are signed in and taken to the workspace dashboard.

Registration creates your workspace, owner account, default roles, and default modules (Leads, Tasks, Communication Templates). The workspace platform domain is generated automatically from the company name (spaces and special characters become hyphens), for example Acme Corp → acme-corp.localhost (or your platform suffix in production). Custom domains require the Branded module after signup.

Login

1. Open /login.
2. Enter your workspace, email, and password. The workspace is preselected when you open the application on its workspace domain.
3. Optionally enable Keep me signed in for 30 days to extend your session to about 30 days on the server. You stay signed in across browser tabs even when this is unchecked; your workspace session length still applies until the token expires.
4. Guest auth pages show the form on the left and a full-bleed image on the right (Central Branding defaults; workspaces with Branded may override the images).
5. Verify your email when prompted; unverified accounts cannot open protected workspace pages. On the verify-email gate, Sign out ends the session and returns you to /login (or /central/login for Central).
6. After success you land on /dashboard.

If a new member never receives the verification email, a workspace owner or admin can open Administration → Users, open that user’s row menu, and either Resend verification or Mark as verified.

Login as another user

Workspace owners (and anyone granted users.impersonate) can open Administration → Users, choose Login as user on a non-owner member, and enter a reason. An amber Impersonation mode is active banner appears until you click End impersonation, which restores your own session. You cannot nest impersonation sessions or impersonate the workspace Owner.

Your browser does not save a workspace selection in local storage. Open the correct workspace host or enter the workspace again when using the shared login URL.

Forgot password

1. Open /forgot-password (or use the link on the login page).
2. Enter your email and submit.
3. If an account exists, you receive a reset email.

Reset password

1. Open the link from your email (/reset-password/{token}?email=…).
2. Enter and confirm a new password that meets platform password rules.
3. After success you are redirected to /login.

Logout

Use Sign out on the tenant dashboard. Your session token is revoked.

Security settings (Profile → Security)

Open Profile (tenant /profile or Central /{prefix}/profile) and choose the Security tab:

Area	What you can do
Password	Change password; optionally sign out all other devices
Two-factor authentication	Enable TOTP with an authenticator app, confirm with a six-digit code, download recovery codes, regenerate codes, or disable
Passkeys	Register device passkeys (Face ID, Touch ID, Windows Hello, security keys), list, and remove
Browser sessions	See active sign-ins, sign out one device, or sign out all other sessions

On the login page you can Sign in with passkey when your browser supports WebAuthn. If two-factor authentication is enabled, password login asks for your authenticator or recovery code after email and password. Passkey sign-in skips the TOTP step when the passkey ceremony succeeds.

Session timeout

If you are idle longer than your workspace Session timeout (or the Central default when the workspace has not overridden it), or your access token expires or is revoked, the application signs you out and returns you to /login (or /central/login for Central). Workspaces can enable Never timeout so idle logout is disabled.

You should not remain on workspace pages seeing load errors after a real session expiry.

---

Central Application (platform admins)

Central auth lives under /{prefix}/* (default prefix central). Operators can set a custom prefix per install via VITE_CENTRAL_PATH_PREFIX / CENTRAL_PATH_PREFIX — see Authentication (developer).

Action	URL (default)
Login	/central/login
Forgot password	/central/forgot-password
Reset password	/central/reset-password/{token}?email=
Admin console	/central/dashboard

Central users are invited by administrators; there is no public Central registration page.

Central administrators must also verify their invited email address before accessing protected Central pages.

Failed Central login attempts email the targeted admin and the platform support mailbox (when configured). After too many failures the account locks temporarily.