Users

Base URL: /api/users · Port 3001 in development.

All endpoints in this group require an authenticated admin unless noted. changeMyPwd is the only exception — it is available to any authenticated role.

Role values: "admin" | "distributor"

POST /api/users/create

Auth required: Yes — admin only

Creates a new user account. The user is created with a default hashed password and is_active = false. An activation email is sent so they can set their own password via PATCH /api/auth/changePwd.

Request body

{
  "name": "John Doe",
  "email": "john@pakag.com",
  "role": "distributor"
}

Response 201

{
  "id": 5,
  "name": "John Doe",
  "email": "john@pakag.com",
  "role": "distributor",
  "is_active": false
}

Errors

Side effect: Inserts user row with bcrypt-hashed default password. Sends an activation email with a one-time token link (expires in 7 days).

GET /api/users/list

Auth required: Yes — admin only

Returns a paginated list of users, optionally filtered by role and/or active status.

Query parameters

Response 200

{
  "users": [
    {
      "id": 1,
      "name": "Admin User",
      "email": "admin@pakag.com",
      "role": "admin",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Errors

GET /api/users/getById

Auth required: Yes — admin only

Returns the full profile of a single user by ID.

Query parameters

Response 200

{
  "id": 3,
  "name": "Jane Smith",
  "email": "jane@pakag.com",
  "role": "distributor",
  "is_active": true,
  "created_at": "2024-01-15T10:00:00.000Z",
  "updated_at": "2024-03-01T08:30:00.000Z"
}

Errors

PATCH /api/users/update

Auth required: Yes — admin only

Partially updates one or more fields of an existing user. At least one field (besides id) must be provided.

Request body

{
  "id": 3,
  "name": "Jane Doe",
  "is_active": false
}

Response 200

{
  "id": 3,
  "name": "Jane Doe",
  "email": "jane@pakag.com",
  "role": "distributor",
  "is_active": false
}

Errors

DELETE /api/users/remove

Auth required: Yes — admin only

Permanently deletes a user. A user cannot delete themselves.

Query parameters

Response 204 — No content.

Errors

Side effect: Deletes the user row. Refresh, reset, and activation tokens linked to the user are removed by DB cascade.

PATCH /api/users/changeMyPwd

Auth required: Yes — admin or distributor (Bearer token)

Allows any authenticated user to change their own password.

Request body

{
  "current_password": "oldSecret",
  "new_password": "newSecret123"
}

Response 200

{ "message": "Password updated successfully" }

Errors