Users

The Admin Users module provides user management capabilities for administrators, including user retrieval with filtering and user role/permission updates within the DashClicks platform.

🎯 Overview

This module handles administrative user operations with role-based access control, supporting user listing with advanced filtering and user permission management across ACM and Projects modules.

🔧 Service Methods

getUsers()

Retrieves users with administrative filtering and role-based access control.

Key Features:

• Permission Validation: Access restricted to owners, managers, and admins
• Role Filtering: Filter by ACM-only or Projects-only users
• Search Functionality: Search across name, email, first_name, last_name
• Role-specific Filtering: Filter by specific project roles
• Secure Projection: Returns only name, image, dashclicks roles, and SSO status

API Endpoint: GET /v1/admin/users

Parameters:

• acmOnly - Filter users with ACM roles only
• projectsOnly - Filter users with Projects roles only
• search - Search across user name/email fields
• role - Filter by specific project roles

updateUser()

Updates user roles, permissions, and SSO settings with comprehensive validation.

Key Features:

• Role Management: Update ACM and Projects roles with validation
• SSO Configuration: Enable/disable SSO access for users
• Team Lead Validation: Ensures team lead constraints are maintained
• Workload Reassignment: Automatically reassigns workload when removing project roles
• Permission Checks: Enforces hierarchical permission system

API Endpoint: PUT /v1/admin/users

Parameters:

• id - User ID to update
• dashclicks - New role configuration object
• sso - SSO configuration settings

🏗️ Technical Architecture

Database Collections

Primary Collections:

• _users - User accounts with role information and permissions
• _admin-teams - Administrative team assignments for validation

Permission System

Access Control Hierarchy:

• Account Owners: Full access to all user management functions
• Super Managers (ACM): Can view and modify users (except other super managers)
• Managers (ACM): Can view and modify users (limited scope)
• Project Admins: Can view and modify project-related users
• Account Managers (Projects): Can view and modify account-level users

Business Logic

Role Management:

• Team Lead Constraints: Validates team lead assignments to prevent conflicts
• Workload Reassignment: Automatically handles workload when removing project roles
• Permission Validation: Enforces hierarchical permission checks
• SSO Management: Controls Single Sign-On access and settings

🔐 Authorization Framework

Permission Validation

For getUsers():

• Account owners have unrestricted access
• Super Managers and Managers (ACM) can view users
• Project Admins and Account Managers can view project users
• All others receive forbidden access error

For updateUser():

• Account owners can modify any user
• Non-owners cannot modify super managers or owners
• Project role modifications require appropriate project permissions
• Team lead role changes trigger team validation

Security Features

• Role Hierarchy Enforcement: Prevents privilege escalation
• Team Integrity: Maintains team lead requirements
• Audit Trail: Tracks all user modifications
• Input Validation: Validates all role assignments and SSO settings

📊 API Response Format

Get Users Response

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "_id": "user_id",
      "name": "User Name",
      "image": "profile_image_url",
      "dashclicks": {
        "acm": { "role": "manager" },
        "projects": { "role": "admin", "auto_assign": true }
      },
      "sso": { "active": true, "impersonate": true, "scope": ["*"] }
    }
  ]
}

Update User Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "user_id",
    "name": "Updated User Name",
    "image": "profile_image_url",
    "dashclicks": {
      "acm": { "role": "team_lead" },
      "projects": { "role": "account_manager" }
    },
    "sso": { "active": false }
  }
}

📝 Usage Examples

Basic User Retrieval

// Get all accessible users
const users = await getUsers({
  accId: accountId,
  isOwner: false,
  dashclicks: { acm: { role: 'manager' } },
});

// Filter ACM users only
const acmUsers = await getUsers({
  accId: accountId,
  isOwner: true,
  dashclicks: adminRoles,
  acmOnly: true,
});

User Role Updates

// Update user roles
const updatedUser = await updateUser({
  accId: accountId,
  userId: targetUserId,
  isOwner: false,
  dashclicks: currentUserRoles,
  newDashclicks: {
    acm: { role: 'team_lead' },
    projects: { role: 'account_manager', auto_assign: false },
  },
  sso: { active: true },
});

⚠️ Important Notes

• Role-based Access: All operations enforce strict permission hierarchies
• Team Lead Validation: Team lead role changes trigger team membership validation
• Workload Management: Removing project roles automatically reassigns user workload
• SSO Control: SSO settings can be enabled/disabled with full scope control