Users Endpoints
Detailed API reference for user management — list, create, get, and update user accounts.
Users Endpoints
Base path: /api/v1/users
Authentication: All routes require a valid JWT token.
GET /users
Returns all user accounts with passwords excluded.
Access Control
- Allowed roles:
ROLE_ADMIN,ROLE_LIBRARIAN
Request
GET /api/v1/users
Authorization: Bearer <token>Response — 200 OK
{
"users": [
{
"_id": "64b8f3a2...",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@university.edu",
"role": "ROLE_STUDENT",
"isActive": true,
"rollNumber": "21CS1004",
"contactNumber": "+1234567890",
"createdAt": "2026-07-01T10:00:00.000Z"
}
]
}POST /users
Creates a new user account.
Access Control
- Allowed roles:
ROLE_ADMINonly
Request
POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json{
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@university.edu",
"contactNumber": "+9876543210",
"role": "ROLE_STUDENT",
"rollNumber": "22CS2001",
"password": "initial_password"
}| Field | Type | Required | Description |
|---|---|---|---|
firstName | string | ✅ | User's first name |
lastName | string | ✅ | User's last name |
email | string | ✅ | Unique email address |
contactNumber | string | ✅ | Unique phone number |
role | string | — | One of the role enums (defaults to ROLE_STUDENT) |
rollNumber | string | — | University roll number (unique, for students) |
password | string | ✅ | Password (hashed with bcrypt before storage) |
Response — 201 Created
{
"user": {
"_id": "64c9b...",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@university.edu",
"role": "ROLE_STUDENT",
"isActive": true,
"rollNumber": "22CS2001"
}
}Error Responses
| Status | Body | When |
|---|---|---|
500 | { "error": "Internal server error (possibly duplicate email/rollNumber)" } | Duplicate unique field |
GET /users/:id
Returns a single user by their MongoDB ObjectId.
Access Control
- Allowed roles:
ROLE_ADMIN,ROLE_LIBRARIAN
Request
GET /api/v1/users/64b8f3a2e7d1c...
Authorization: Bearer <token>Response — 200 OK
{
"user": {
"_id": "64b8f3a2...",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@university.edu",
"role": "ROLE_STUDENT",
"isActive": true
}
}Error Responses
| Status | Body | When |
|---|---|---|
404 | { "error": "User not found" } | No user with that ID |
PATCH /users/:id
Updates user fields. Supports partial updates.
Access Control
- Allowed roles:
ROLE_ADMIN,ROLE_LIBRARIAN
Request
PATCH /api/v1/users/64b8f3a2e7d1c...
Authorization: Bearer <token>
Content-Type: application/json{
"firstName": "Jonathan",
"role": "ROLE_STAFF",
"password": "new_password_123"
}Password Handling
If password is included in the request body, it is extracted and hashed before being saved:
const { password, ...updateData } = req.body;
if (password) {
updateData.passwordHash = await bcrypt.hash(password, 10);
}Deactivating a User
{
"isActive": false
}Response — 200 OK
{
"user": {
"_id": "64b8f3a2...",
"firstName": "Jonathan",
"role": "ROLE_STAFF",
"isActive": true
}
}