User Management

Manage dashboard users, roles, permissions, and access control for your AgenticMail Enterprise instance.

Overview
How It Works
Key Concepts
Role System
Permission Editor
Agent Access Control
Client Organization Assignment
User Lifecycle
Configuration & Setup
Best Practices
Troubleshooting
Related Pages

Overview

For everyone: The Users page is where you manage who can access your AgenticMail Enterprise dashboard and what they can see and do. Think of it as the "guest list" for your control center — you decide who gets in, what rooms they can enter, and which agents they can interact with.

For technical users: This page implements a full RBAC (Role-Based Access Control) system with page-level and tab-level permission granularity, per-user agent access restrictions, client organization scoping, and a multi-step destructive action workflow. The backend exposes /users, /users/:id/permissions, /page-registry, and /organizations API endpoints.

How It Works

Create a user — provide email, initial password, name, and role. The user is forced to change their password on first login.
Assign a role — Owner and Admin get full access automatically. Member and Viewer roles can be restricted via the Permission Editor.
Configure permissions — Click the shield icon on any Member/Viewer to control which pages, tabs, and agents they can access.
Optionally bind to an organization — Restrict a user to only see agents and data belonging to a specific client organization.
Manage lifecycle — Edit, deactivate, reactivate, reset passwords, impersonate, or permanently delete users as needed.

Key Concepts

Page Registry

The backend maintains a registry of all dashboard pages and their tabs. This registry is fetched via GET /page-registry and used by the Permission Editor to generate the access control UI. Pages are organized into three sections:

Section	Description
Overview	Dashboard home, analytics, and monitoring pages
Management	Agent management, email, tools, and operational pages
Administration	Users, vault, compliance, DLP, and system settings

Permission Format

Permissions are stored as a JSON object or the string "*" for full access:

// Full access
"*"

// Granular access — page IDs as keys, true or tab array as values
{
  "agents": true,              // All tabs on agents page
  "vault": ["secrets", "audit"], // Only secrets and audit tabs
  "_allowedAgents": ["agent-id-1", "agent-id-2"]  // Specific agents only
}

Role System

Role	Access Level	Permissions Configurable?	Notes
Owner	Full	No — always full	Cannot be restricted. Can impersonate other users.
Admin	Full	No — always full	Cannot be restricted. Full administrative access.
Member	Configurable	Yes	Can view and act on assigned pages/tabs.
Viewer	Configurable (read-only)	Yes	Can view but not modify.

Tip: Owner and Admin users always have full access to all pages — the Permission Editor only affects Member and Viewer roles.

Permission Editor

The Permission Editor (shield icon) opens a modal where you can configure:

Full Access toggle — grants unrestricted access to all pages, tabs, and agents.
Page-level access — check/uncheck individual pages grouped by section (Overview, Management, Administration).
Tab-level access — for pages with tabs (e.g., Agents), expand the page to grant access to specific tabs only.
Quick actions — "Select All" and "Select None" buttons for bulk toggling.
Agent access — restrict which agents the user can see and manage (see below).
Organization assignment — bind user to a client organization.

The editor also shows an inline permission picker when creating new users with Member or Viewer roles, so you can set permissions before the user is created.

Agent Access Control

Beyond page/tab permissions, you can control which agents a user can see:

All Agents (default) — the user can see and manage every agent in the system.
Specific agents — uncheck "All Agents" and select individual agents from the list. The user will only see these agents across the entire dashboard.

Warning: If you select no agents, the user will see an empty agent list everywhere. Make sure at least one agent is selected.

Client Organization Assignment

If your deployment uses multi-tenancy with client organizations:

Assign a user to a client organization to restrict them to only that organization's agents and data.
The organization switcher will be locked for that user — they cannot switch to other orgs.
Users without an org assignment are "Internal Users" and can see everything (subject to their role and permissions).

User Lifecycle

Creating Users

Click "Add User" and fill in name, email, initial password (or generate one), and role. For Member/Viewer roles, you can customize permissions inline before creating.

Tip: Use the "Generate" button to create a strong random password. The user will be required to change it on first login.

Editing Users

Click the edit icon to change a user's name, role, or organization. Email cannot be changed after creation.

Resetting Passwords

Click the lock icon to set a new password. If the user has 2FA enabled, the password reset will not affect their TOTP setup.

Impersonation (Owner Only)

Owners can click the impersonate icon to view the dashboard as another user, seeing exactly what they see based on their permissions. Useful for debugging access issues.

Deactivation vs. Deletion

Action	Reversible?	Effect
Deactivate	Yes	Blocks login. All data preserved. User sees "contact your organization" message.
Delete	No	Permanently removes user, sessions, API keys, permissions, and 2FA config.

Danger: Deletion is a 5-step process requiring you to type the user's email to confirm. It cannot be undone. Always prefer deactivation unless you are certain.

5-Step Delete Confirmation

Warning — confirms you understand this is permanent.
Data loss — lists all data that will be lost (sessions, audit references, API keys, 2FA).
Impact assessment — warns about orphaned agent assignments, approval workflows, and cron jobs.
Alternative suggestion — recommends deactivation as the safe option.
Final confirmation — type the user's email to confirm deletion.

Configuration & Setup

API Endpoints

Method	Endpoint	Description
GET	`/users`	List all users
POST	`/users`	Create a new user
PATCH	`/users/:id`	Update user (name, role, clientOrgId)
DELETE	`/users/:id`	Permanently delete user (requires confirmation token)
GET	`/users/:id/permissions`	Get user permissions
PUT	`/users/:id/permissions`	Update user permissions
POST	`/users/:id/reset-password`	Reset user password
POST	`/users/:id/deactivate`	Deactivate user
POST	`/users/:id/reactivate`	Reactivate user
GET	`/page-registry`	Get page/tab registry for permission editor
GET	`/organizations`	List client organizations

User Table Columns

The users table displays: Name, Email, Role, Organization, Status (Active/Deactivated), Access (Full or page count), 2FA (On/Off), Created date, and Actions.

Best Practices

Principle of least privilege — start users with Viewer role and only elevate as needed.
Use organizations — for multi-tenant setups, always bind external users to their client org.
Prefer deactivation — deactivate users who leave the team instead of deleting them, preserving audit trail integrity.
Limit Owner accounts — only 1–2 users should have Owner role. Use Admin for day-to-day administration.
Review permissions quarterly — audit who has access to what and remove unnecessary grants.
Use tab-level restrictions — if a Member only needs to see agent logs but not configuration, restrict at the tab level.
Generate passwords — always use the Generate button rather than creating weak passwords manually.

Troubleshooting

User can't see certain pages

Check their role and permissions. If they're a Member or Viewer, click the shield icon to verify which pages are granted. Remember that Owner and Admin roles always have full access.

User can't see any agents

The agent access control may be set to specific agents with none selected. Open the Permission Editor and either check "All Agents" or select specific agents.

Organization switcher is locked

The user is bound to a client organization. Edit the user and change their organization to "None (Internal User)" to unlock it.

"Cannot delete user" error

Ensure you're sending the correct confirmation token: DELETE_USER_{email}. Only Owners can delete users, and you cannot delete yourself.

Permissions not taking effect

The user may need to refresh their browser or log out and back in for permission changes to take effect.

2FA still active after password reset

This is by design — resetting a password does not disable two-factor authentication. The user's TOTP setup is preserved.

Vault — Manage secrets and credentials that users access. Compliance — Generate audit reports that reference user actions. DLP — Data loss prevention rules that apply to user-managed agents.

AgenticMail Enterprise Documentation Report an issue

User Management

Table of Contents

Overview

How It Works

Key Concepts

Page Registry

Permission Format

Role System

Permission Editor

Agent Access Control

Client Organization Assignment

User Lifecycle

Creating Users

Editing Users

Resetting Passwords

Impersonation (Owner Only)

Deactivation vs. Deletion

5-Step Delete Confirmation

Configuration & Setup

API Endpoints

User Table Columns

Best Practices

Troubleshooting

User can't see certain pages

User can't see any agents

Organization switcher is locked

"Cannot delete user" error

Permissions not taking effect

2FA still active after password reset

Related Pages