Multi-User Management

Relevant source files

• frontend/src/App.jsx
• frontend/src/AuthContext.jsx
• frontend/src/components/SettingsSidebar/index.jsx
• frontend/src/models/system.js
• frontend/src/utils/paths.js
• server/endpoints/admin.js
• server/endpoints/api/admin/index.js
• server/endpoints/system.js

Purpose and Scope

This document covers the multi-user management system in AnythingLLM, including role-based access control (RBAC), user lifecycle management, invitation system, and workspace-level permissions. It details how the system supports both single-user and multi-user deployment modes, and how administrators and managers control user access.

For authentication mechanisms (JWT, password hashing, session management), see Authentication System. For workspace-level configuration and settings inheritance, see Workspace Configuration.

---

Deployment Modes

AnythingLLM operates in one of two modes, controlled by the multi_user_mode setting in the system_settings database table.

Single-User Mode

In single-user mode, the instance is protected by an optional instance password (AUTH_TOKEN environment variable). All requests are authenticated with this single credential, and there is no concept of individual users or roles.

Sources: server/endpoints/system.js296-329 server/endpoints/system.js647-655

Multi-User Mode

Multi-user mode enables:

• Individual user accounts with usernames and passwords
• Role-based access control (admin, manager, default)
• Per-user workspace access
• User suspension capabilities
• Invitation-based registration

Enabling Multi-User Mode

The transition from single-user to multi-user mode is one-way and irreversible:

Sources: server/endpoints/system.js591-644 frontend/src/models/system.js204-215

The enabling process performs the following operations:

1. Creates the first admin user (username + password)
2. Updates SystemSettings to set multi_user_mode: true
3. Generates or confirms JWT_SECRET for token signing
4. Migrates any existing API keys to the new admin user via BrowserExtensionApiKey.migrateApiKeysToMultiUser()
5. Logs telemetry and event logs

Sources: server/endpoints/system.js619-633

---

User Model and Database Schema

users Table Structure

The users table tracks all user accounts in multi-user mode:

Field	Type	Description
id	INTEGER	Primary key
username	TEXT	Unique username for login
password	TEXT	bcrypt-hashed password
role	TEXT	Role: 'admin', 'manager', 'default'
suspended	INTEGER	0 = active, 1 = suspended
pfpFilename	TEXT	Profile picture filename (nullable)
seen_recovery_codes	BOOLEAN	Whether user has viewed recovery codes
createdAt	DATETIME	Account creation timestamp
lastUpdatedAt	DATETIME	Last modification timestamp

Sources: Based on usage patterns in server/models/user.js

Role Hierarchy

Sources: server/utils/middleware/multiUserProtected.js server/endpoints/admin.js36-46

Role Constants

The system defines roles in server/utils/middleware/multiUserProtected.js:

Sources: server/utils/middleware/multiUserProtected.js39

---

User Lifecycle Management

User Creation

Role Validation Rules

The validRoleSelection() function enforces these constraints:

• Managers cannot create or modify admin users
• Managers can only create default or manager users
• Admins can create any role
• Role must be one of: 'admin', 'manager', 'default'

Sources: server/endpoints/admin.js49-82 server/utils/helpers/admin.js

User Update

User updates follow similar validation patterns with additional protections:

Last Admin Protection

The canModifyAdmin() function prevents:

• Demoting the last admin in the system
• Suspending the last admin in the system

Sources: server/endpoints/admin.js85-123 server/utils/helpers/admin.js

User Deletion

User deletion is permanent and cascades to related records:

Cascade Effects:

• Removes workspace associations (workspace_users table)
• Deletes API keys owned by user
• Removes invite codes created by user
• Preserves chat history (chats are not deleted, but association is broken)

Sources: server/endpoints/admin.js126-155

User Suspension

Suspended users (suspended = 1) cannot:

• Log in to the system
• Access any workspaces
• Use API keys
• Be impersonated via invitation system

Suspended status is checked at:

1. Login time: server/endpoints/system.js238-254
2. Token validation: server/endpoints/system.js118-127
3. Refresh user: server/endpoints/system.js161-166

Sources: server/endpoints/system.js238-254 server/endpoints/system.js118-127

---

Invitation System

The invitation system enables admins and managers to create registration links for new users.

Invite Model

Sources: server/models/invite.js server/endpoints/admin.js158-221

Invite Workflow

Sources: server/endpoints/admin.js172-201 server/models/invite.js

Invite States

Status	Description
pending	Unused invite, can be claimed
accepted	Used by a user, cannot be reused
disabled	Deactivated by admin, cannot be claimed

Sources: server/models/invite.js

---

Workspace Permissions

Workspace access is controlled via the workspace_users join table.

Permission Model

Sources: server/models/workspaceUsers.js server/models/workspace.js

Managing Workspace Users

Add Users to Workspace

The /admin/workspaces/:workspaceSlug/manage-users endpoint supports two modes:

1. Additive mode (reset: false, default):

   • Adds specified users to workspace
   • Preserves existing users
   • Admins always have access (no explicit entry needed)

2. Reset mode (reset: true):

   • Removes all current users
   • Adds only the specified users
   • Overwrites previous permissions

Sources: server/endpoints/api/admin/index.js547-659

Workspace Access Patterns

Scenario	Access Granted?
Admin user, no workspace_users entry	✓ Yes (admins bypass check)
Manager user, no workspace_users entry	✗ No
Default user, has workspace_users entry	✓ Yes
Default user, no workspace_users entry	✗ No
Suspended user, has workspace_users entry	✗ No (suspension overrides all)

Sources: server/utils/middleware/multiUserProtected.js

---

Middleware and Access Control

Middleware Functions

The multiUserProtected.js file provides role-based middleware:

Middleware Types:

1. strictMultiUserRoleValid([roles])

   • Enforces role requirement in multi-user mode
   • Blocks request if mode is single-user
   • Used for user management endpoints

2. flexUserRoleValid([roles])

   • Enforces role requirement in multi-user mode
   • Allows request in single-user mode (backwards compatibility)
   • Used for system configuration endpoints

3. isMultiUserSetup

   • Simple boolean check for multi-user mode enabled
   • Does not validate role

Sources: server/utils/middleware/multiUserProtected.js server/endpoints/admin.js35-47

Role Checking Examples

Endpoint	Middleware	Required Roles
POST /admin/users/new	strictMultiUserRoleValid	admin, manager
POST /system/update-env	flexUserRoleValid	admin
GET /admin/workspaces	strictMultiUserRoleValid	admin, manager
DELETE /system/remove-document	flexUserRoleValid	admin, manager
GET /system/pfp/:id	flexUserRoleValid	all (any authenticated user)

Sources: server/endpoints/system.js server/endpoints/admin.js

---

Frontend Integration

AuthContext Provider

The AuthContext manages authentication state in the React frontend:

Token Refresh Mechanism:

On mount and whenever store.authToken changes, the AuthContext calls System.refreshUser():

If the user is suspended or session is invalid, the context clears all auth data and redirects to login.

Sources: frontend/src/AuthContext.jsx50-72 server/endpoints/system.js143-180

User Profile Management

Users can upload and manage their profile picture (pfp):

Profile Picture Endpoints:

• Upload: POST /system/upload-pfp (roles: all)
• Fetch: GET /system/pfp/:id (roles: all, user can only fetch own pfp)
• Remove: DELETE /system/remove-pfp (roles: all)

Sources: server/endpoints/system.js764-801 server/endpoints/system.js855-888

---

API Endpoints Reference

Admin User Management

Method	Endpoint	Roles	Description
GET	/admin/users	admin, manager	List all users
POST	/admin/users/new	admin, manager	Create new user
POST	/admin/user/:id	admin, manager	Update user by id
DELETE	/admin/user/:id	admin, manager	Delete user by id

API Version:

Method	Endpoint	Roles	Description
GET	/v1/admin/users	API key	List all users
POST	/v1/admin/users/new	API key	Create new user
POST	/v1/admin/users/:id	API key	Update user by id
DELETE	/v1/admin/users/:id	API key	Delete user by id

Sources: server/endpoints/admin.js35-155 server/endpoints/api/admin/index.js41-267

Invitation Management

Method	Endpoint	Roles	Description
GET	/admin/invites	admin, manager	List all invites
POST	/admin/invite/new	admin, manager	Create new invite
DELETE	/admin/invite/:id	admin, manager	Deactivate invite

API Version:

Method	Endpoint	Roles	Description
GET	/v1/admin/invites	API key	List all invites
POST	/v1/admin/invite/new	API key	Create new invite
DELETE	/v1/admin/invite/:id	API key	Deactivate invite

Sources: server/endpoints/admin.js158-221 server/endpoints/api/admin/index.js270-422

Workspace User Management

Method	Endpoint	Roles	Description
GET	/admin/workspaces/:workspaceId/users	admin, manager	List users with workspace access
POST	/admin/workspaces/:workspaceId/update-users	admin, manager	Deprecated: Overwrite workspace users
POST	/v1/admin/workspaces/:workspaceSlug/manage-users	API key	Add/reset workspace users

manage-users Request Body:

Sources: server/endpoints/admin.js238-288 server/endpoints/api/admin/index.js425-659

System Endpoints

Method	Endpoint	Roles	Description
POST	/system/enable-multi-user	none (pre-auth)	Enable multi-user mode
GET	/system/multi-user-mode	none	Check if multi-user mode enabled
POST	/system/recover-account	none	Recover account with recovery codes
POST	/system/reset-password	none	Reset password with token
GET	/system/refresh-user	validated token	Refresh user object from session

Sources: server/endpoints/system.js591-655

---

Security Considerations

Password Security

• Passwords are hashed using bcrypt with salt rounds = 10
• Stored hashes in users.password column
• Plain text passwords never logged or stored

Sources: server/models/user.js

Recovery Codes

Upon first login, users receive single-use recovery codes for account recovery:

Recovery codes are:

• Generated once per user
• Displayed only on first login
• Stored as bcrypt hashes (single-use)
• Used via POST /system/recover-account

Sources: server/endpoints/system.js277-287 server/utils/PasswordRecovery/index.js

Session Management

JWT tokens contain:

• id: User ID
• username: Username
• Expiry time controlled by JWT_EXPIRY env var (default: "30d")

The userFromSession() helper extracts and validates the user on each request:

Sources: server/utils/http.js

Suspension Enforcement

Suspended users are blocked at multiple layers:

1. Login attempt returns 403
2. Token validation checks suspension status
3. User refresh endpoint returns error
4. Frontend AuthContext logs out suspended users

Sources: server/endpoints/system.js238-254 frontend/src/AuthContext.jsx50-72

---

Frontend Components

Settings Sidebar

The settings sidebar dynamically shows options based on user role:

Each Option component checks user.role against allowed roles array before rendering.

Sources: frontend/src/components/SettingsSidebar/index.jsx214-419

Role-Based Rendering

Components use patterns like:

The Option component filters out options where user.role is not in roles array.

Sources: frontend/src/components/SettingsSidebar/MenuOption.jsx

---

Common Workflows

Creating a New User (Admin)

1. Navigate to Settings → Admin → Users
2. Click "Add User"
3. Provide username, password, and select role
4. Frontend calls POST /admin/users/new
5. Backend validates role selection based on creator's role
6. Backend hashes password with bcrypt
7. Backend inserts into users table
8. Backend logs user_created event
9. Frontend refreshes user list

Sources: server/endpoints/admin.js49-82

Inviting a User (Admin/Manager)

1. Navigate to Settings → Admin → Invites
2. Click "Create Invite"
3. Optionally select workspaces to grant access
4. Frontend calls POST /admin/invite/new
5. Backend generates unique UUID code
6. Backend creates invites record and workspace_invite entries
7. Admin shares invite URL with new user
8. New user visits /invite/:code and registers
9. Backend creates user, marks invite as accepted, assigns workspaces

Sources: server/endpoints/admin.js172-201

Assigning Workspace Access

1. Admin navigates to Settings → Admin → Workspaces
2. Clicks "Manage Users" for a workspace
3. Selects users to grant access
4. Frontend calls POST /admin/workspaces/:id/update-users
5. Backend creates workspace_users entries
6. Users can now access the workspace

Sources: server/endpoints/admin.js272-288

---

Sources: server/endpoints/system.js server/endpoints/admin.js server/models/user.js server/models/invite.js server/models/workspaceUsers.js server/utils/middleware/multiUserProtected.js frontend/src/models/system.js frontend/src/AuthContext.jsx frontend/src/components/SettingsSidebar/index.jsx