Skip to main content

​
Overview

The User Management API provides endpoints for administrators to manage user accounts, assign roles, and control access. Most endpoints require Admin role, with some accessible to Managers.

​
Get All Users

Retrieve all users with pagination and filtering. Access: Private (Admin only)

​
Query Parameters

​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"10"
Number of users per page
​
role
string
Filter by role: Admin, Manager, or Worker
​
isActive
boolean
Filter by active status (true or false)
​
search
string
Search by name or email

​
Response

{
  "success": true,
  "message": "Users fetched successfully",
  "data": {
    "users": [
      {
        "_id": "65a1234567890abcdef12345",
        "name": "John Doe",
        "email": "[email protected]",
        "role": "Worker",
        "isActive": true,
        "createdAt": "2024-01-10T10:00:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 3,
      "totalUsers": 25,
      "limit": 10
    }
  }
}

​
Get User by ID

Get a single user by ID. Access: Private (Admin only)

​
Response

{
  "success": true,
  "message": "User fetched successfully",
  "data": {
    "user": {
      "_id": "65a1234567890abcdef12345",
      "name": "John Doe",
      "email": "[email protected]",
      "role": "Worker",
      "isActive": true,
      "createdAt": "2024-01-10T10:00:00.000Z"
    }
  }
}

​
Create User

Create a new user account. Access: Private (Admin only)

​
Request Body

​
name
string
required
User’s full name
​
email
string
required
User’s email address (must be unique)
​
password
string
required
User’s password
​
role
string
required
User role: Admin, Manager, or Worker

​
Example Request

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "password": "securepass123",
  "role": "Manager"
}

​
Example Response

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "user": {
      "_id": "65a9876543210fedcba98765",
      "name": "Jane Smith",
      "email": "[email protected]",
      "role": "Manager",
      "isActive": true
    }
  }
}

​
Update User

Update a user’s information. Access: Private (Admin only)

​
Request Body

All fields are optional. Only provided fields will be updated.
​
name
string
Updated name
​
email
string
Updated email (must be unique)
​
role
string
Updated role: Admin, Manager, or Worker
​
isActive
boolean
Account status (true = active, false = deactivated)

​
Example Request

{
  "name": "Jane Smith-Johnson",
  "role": "Admin",
  "isActive": true
}

​
Example Response

{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "user": {
      "_id": "65a9876543210fedcba98765",
      "name": "Jane Smith-Johnson",
      "email": "[email protected]",
      "role": "Admin",
      "isActive": true
    }
  }
}
Deactivated users (isActive: false) cannot log in to the system.

​
Delete User

Delete a user account. Access: Private (Admin only)

​
Response

{
  "success": true,
  "message": "User deleted successfully",
  "data": null
}
Admins cannot delete their own account. This prevents accidental lockout.

​
Get Workers

Get all active workers (for task assignment). Access: Private (Manager/Admin only)

​
Response

​
workers
array
Array of active workers
​
_id
string
Worker ID
​
name
string
Worker name
​
email
string
Worker email
​
count
number
Number of active workers

​
Example Response

{
  "success": true,
  "message": "Workers fetched successfully",
  "data": {
    "workers": [
      {
        "_id": "65a1234567890abcdef12345",
        "name": "John Doe",
        "email": "[email protected]"
      },
      {
        "_id": "65a9876543210fedcba98765",
        "name": "Alice Johnson",
        "email": "[email protected]"
      }
    ],
    "count": 2
  }
}
This endpoint only returns users with the “Worker” role who have isActive set to true. It’s commonly used to populate task assignment dropdowns.

​
Get User Statistics

Get user statistics for admin dashboard. Access: Private (Admin only)

​
Response

​
stats
object
​
totalUsers
number
Total number of users
​
activeUsers
number
Number of active users
​
inactiveUsers
number
Number of inactive users
​
byRole
object
User count by role
​
Admin
number
Number of admins
​
Manager
number
Number of managers
​
Worker
number
Number of workers

​
Example Response

{
  "success": true,
  "message": "User statistics fetched successfully",
  "data": {
    "stats": {
      "totalUsers": 25,
      "activeUsers": 22,
      "inactiveUsers": 3,
      "byRole": {
        "Admin": 2,
        "Manager": 5,
        "Worker": 18
      }
    }
  }
}

​
User Roles

RoleDescriptionCapabilities
AdminFull system accessAll operations including user management
ManagerOperational managementInventory management, task management, analytics, view workers
WorkerTask executionView own tasks, update task status, view inventory

​
Role-Based Access

EndpointWorkerManagerAdmin
GET /users❌❌✅
GET /users/:id❌❌✅
POST /users❌❌✅
PUT /users/:id❌❌✅
DELETE /users/:id❌❌✅
GET /users/workers❌✅✅
GET /users/stats❌❌✅

​
Error Responses

​
400 Bad Request

{
  "success": false,
  "message": "Please provide all required fields"
}

​
403 Forbidden

{
  "success": false,
  "message": "You cannot delete your own account"
}

​
404 Not Found

{
  "success": false,
  "message": "User not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us