Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vanegasjoseignacio2-cyber/Eco-It/llms.txt

Use this file to discover all available pages before exploring further.

The Eco-It user management system gives administrators complete visibility and control over every registered account. Admins can list all users, search and filter by role or status, apply temporary bans, lift bans early, and delete accounts entirely. Role promotion and demotion are reserved exclusively for superadmins. All write operations emit real-time Socket.io events so that affected users — and other connected admins — are notified instantly.
Role changes (PATCH /api/admin/users/:id/role) are protected by the soloSuperadmin middleware and will return 403 Forbidden for admin-role callers. No admin can change their own role.

​
User Model Fields

The following fields from the User model are most relevant to admin operations. Sensitive fields such as password, resetPasswordToken, and resetPasswordExpires are stripped from all admin API responses.
​
nombre
string
required
The user’s first name.
​
apellido
string
The user’s last name. Required for locally registered accounts; optional for Google OAuth accounts.
​
email
string
required
Unique, lowercase email address. Used as the primary identifier in audit log entries.
​
rol
string
One of user, admin, or superadmin. Defaults to user on registration.
​
status
string
One of active, inactive, or banned. Defaults to active.
​
banHasta
Date | null
The UTC datetime at which the ban expires. null when the user is not banned. The verificarToken middleware automatically lifts an expired ban on the next login attempt.
​
banReason
string | null
Human-readable reason stored at ban time. null when the user is not banned.
​
ultimaConexion
Date | null
Timestamp of the user’s most recent socket connection. Useful for identifying inactive accounts.
​
puntos
number
Eco-It gamification points accumulated by the user. Displayed as a progress bar in the admin Users table.
​
isOnline
boolean
Virtual field appended by the API response. true if the user’s ID is present in the live usuariosConectados Map.

​
API Endpoints

​
List All Users

Returns an array of all registered users sorted by createdAt descending, with sensitive fields omitted. Each user object includes the virtual isOnline flag derived from the live socket connections map. 
GET /api/admin/usuarios
Authorization: Bearer <token>
Success response: 
{
  "success": true,
  "usuarios": [
    {
      "_id": "664f1a2b3c4d5e6f7a8b9c0d",
      "nombre": "Valentina",
      "apellido": "Torres",
      "email": "valentina@example.com",
      "rol": "user",
      "status": "active",
      "banHasta": null,
      "banReason": null,
      "puntos": 340,
      "ultimaConexion": "2024-11-01T14:22:00.000Z",
      "isOnline": true,
      "createdAt": "2024-09-15T10:00:00.000Z"
    }
  ]
}

​
Platform Statistics

Returns KPI totals and time-series chart data used by the admin Dashboard. Runs multiple MongoDB aggregations in parallel to minimize latency. 
GET /api/admin/stats
Authorization: Bearer <token>
Response fields:
​
totalUsuarios
number
Total registered user count.
​
usuariosOnline
number
Real-time count of users with at least one active socket connection.
​
consultasHoy
number
Number of EcoBot (AI) queries sent today by regular users.
​
nuevosHoy
number
New accounts created since midnight of the current day.
​
totalPuntos
number
Sum of puntos across all user documents.
​
chartData
object
Time-series arrays for charting: users, queries, usersMonth, queriesMonth, usersWeek, queriesWeek. Each array contains objects with { label, value }.

​
Ban a User

Sets status to "banned", computes the banHasta expiry date, and stores the banReason. Emits admin:usuario_baneado to the admins Socket.io room and user:banned directly to the affected user’s socket(s). Also creates a Notification document visible to all admins. 
PATCH /api/admin/users/:id/ban
Authorization: Bearer <token>
Content-Type: application/json
Request body:
​
dias
number
default:"7"
Number of days the ban should last. Must be a positive integer (1–365 recommended).
​
motivo
string
default:"Incumplimiento de las normas"
Human-readable reason for the ban. Stored in banReason and included in audit log details.
Example: 
curl -X PATCH https://api.eco-it.co/api/admin/users/664f1a2b3c4d5e6f7a8b9c0d/ban \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "dias": 14, "motivo": "Publicación de contenido inapropiado reiterado" }'
Success response: 
{
  "success": true,
  "message": "Usuario baneado por 14 días",
  "usuario": {
    "_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "status": "banned",
    "banHasta": "2024-11-15T10:30:00.000Z",
    "banReason": "Publicación de contenido inapropiado reiterado"
  }
}
An admin cannot ban themselves (req.usuario.id === id returns 400). The ban check also applies in the verificarToken middleware: if banHasta has passed by the time the user next authenticates, the ban is lifted automatically and the user regains access.

​
Unban a User

Resets status to "active" and sets banHasta to null. Emits user:unbanned to the affected user’s socket(s) for an immediate in-app notification. 
PATCH /api/admin/users/:id/unban
Authorization: Bearer <token>
Success response: 
{
  "success": true,
  "message": "Usuario desbaneado exitosamente",
  "usuario": {
    "_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "status": "active",
    "banHasta": null
  }
}

​
Delete a User

Permanently removes the user document from MongoDB via findByIdAndDelete. Creates an audit log entry recording the deleted email. An admin cannot delete their own account. 
DELETE /api/admin/users/:id
Authorization: Bearer <token>
Success response: 
{
  "success": true,
  "message": "Usuario eliminado exitosamente"
}

​
Change a User’s Role

Promotes or demotes a user between "user" and "admin". Superadmin-only. After the database update, the backend synchronises the user’s live socket room membership — joining or leaving the admins Socket.io room — so the change takes effect without requiring the affected user to log out. 
PATCH /api/admin/users/:id/role
Authorization: Bearer <token>
Content-Type: application/json
​
rol
string
required
The new role. Must be one of "user" or "admin". Passing "superadmin" is explicitly rejected with 400.
Example: 
curl -X PATCH https://api.eco-it.co/api/admin/users/664f1a2b3c4d5e6f7a8b9c0d/role \
  -H "Authorization: Bearer $SUPERADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rol": "admin" }'
Success response: 
{
  "success": true,
  "mensaje": "El rol del usuario ha sido cambiado a admin",
  "usuario": {
    "_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "email": "valentina@example.com",
    "rol": "admin"
  }
}
Rejection cases:
ConditionHTTP StatusMessage
Caller is not superadmin403"Acceso denegado: se requiere rol superadmin"
Targeting own account400"No puedes cambiar tu propio rol"
Target is a superadmin403"No puedes modificar a otro superadmin"
rol is "superadmin"400"No tienes permisos para crear otro superadmin"
Invalid rol value400"Rol inválido"

​
Frontend Filtering

The AdminUsers React component (adminUsers.jsx) supports client-side filtering on the already-fetched user list. No additional API calls are made when filters change.
  • Search: matches against full name (nombre + apellido) and email (case-insensitive).
  • Role filter: dropdown for all, user, admin, superadmin.
  • Status filter: all, active (online), inactive (offline, not banned), banned.
The online/offline computed status derives from the isOnline field returned by the API and updates in real time via the usuario:estado socket event.

Build docs developers (and LLMs) love

Get started for freeTalk to us