# User Management

## Overview

User Management (Admin → Users) is where you manage every person with a login on the platform — workspace owners, team members, agents, and fellow admins. From here you can create accounts, edit profiles and roles, verify emails, suspend troublemakers, force users to log out, send password resets, and move accounts to a recoverable trash.

This is a platform-wide list. It is separate from a workspace's own team management — here you see all users across all workspaces.

## The User List

The index shows a paginated table (12 per page) of every user. A KPI strip at the top counts the total, active, admins, owners, suspended, trashed, and how many joined this month.

You can narrow the list with:

- Search — matches name, email, or mobile number.
- Role filter — show only Admins, Owners, Users, Agents, or Suspended accounts.
- Workspace filter — show only users whose current workspace is a given one.

A filtered view can be bookmarked or shared — the filters are kept in the page address.

## Roles Explained

Every user has exactly one platform-level role. This controls what they can do on the platform, distinct from their per-workspace permission set.

Role | Meaning
--- | ---
Admin | Platform operator. Can access this admin panel.
Owner | Owns one or more workspaces. The typical paying customer.
User | A standard member of a workspace.
Agent | A support/inbox agent seat.
Suspended | Login blocked. Set by the suspend action (see below).

> Important — Super Admin gate: Creating, promoting, or demoting an Admin or Owner account requires Super Admin. A regular admin who tries to mint or promote a privileged account will have the action silently downgraded to a normal User (on create) or reverted (on edit), and the attempt is written to the audit log. The same gate applies to suspending an admin or owner.

## Creating a User

Click Create and fill in the form. Required fields are name, email, role, and a password (minimum 8 characters, confirmed). Everything else — mobile, address, and admin notes — is optional.

Field / toggle | What it does
--- | ---
Name, Email | Required. Email must be unique across the platform.
Password | Required on create, min 8 chars, must match the confirmation field.
Role | One of the roles above. Admin/Owner needs Super Admin.
Workspace | Optionally set the user's current workspace.
Address block | Address, city, state, country, ZIP — all optional, used on invoices.
Force password change | When on, the user must set a new password on first login.
Active immediately | When on, the email is marked verified now (skips the verification step).
Send welcome email | When on, emails login details and a password-reset link.

> Note: If the welcome email can't be sent (for example, if email isn't set up yet), the user is still created successfully — you'll just see a notice explaining why the email was skipped. Creating an account never depends on your mail server working.

## Editing a User

The edit screen lets you change any profile field, reassign the role and workspace, and optionally set a new password (leave the password field blank to keep the existing one).

The Email verified toggle behaves intelligently:

- Turning it on stamps the account as verified immediately.
- Turning it off tries to send a fresh verification email. If email isn't available, the account is left verified so the user isn't locked out — you'll see a notice saying so.

## Per-User Actions

From the edit screen (and the list) you can run several account actions. Each one is recorded in the audit log.

Action | Effect
--- | ---
Suspend / Reactivate | Flips the role between the user's normal role and Suspended, blocking or restoring login. Suspending an admin/owner needs Super Admin.
Reset password | Emails a password-reset link to the user. Rate-limited to 5 sends per admin per hour to prevent abuse.
Force logout | Revokes every active session for the user — they must log in again. Useful after a suspected account compromise.
Move to trash | Soft-deletes the account. Recoverable for 30 days. You cannot trash your own account.

> Tip: If you suspect a stolen session, do both: Reset password (so the old credentials stop working) and Force logout (so any open sessions are killed immediately).

## Trash & Recovery

Deleting a user doesn't wipe them — it moves them to a 30-day trash (Admin → Users → Trash). Each trashed row shows a countdown to permanent deletion. The trash view has its own counters and filters:

- Recent — trashed within the last 7 days.
- Expiring — trashed more than 23 days ago (less than a week until auto-delete).

From the trash you can:

- Restore — un-delete a single user and return them to the active list.
- Force delete — permanently wipe one user immediately.
- Empty trash — permanently delete every user already past the 30-day grace window.

> Caution: Force delete and Empty trash are irreversible. There is no second trash — once a record is force-deleted it's gone. Prefer plain "Move to trash" unless you're certain.

## Bulk Import

The Import screen lets you add many users at once instead of creating them one by one. Use it when moving an existing customer base onto the platform.

## Auditing

Sensitive actions on this page — role changes, suspensions, force-logout, password resets, restores, and permanent deletes — are all written to the platform Audit Log. Denied privileged attempts (e.g. a non-Super-Admin trying to promote someone) are logged as failures too, so you have a record of who tried what.