This document details the API endpoints exposed by the backend server. All requests must carry JSON payloads (where applicable) and use the base URL (e.g. http://localhost:3000/api).
- Method:
POST - Route:
/signIn - Purpose: Authenticate user credentials and retrieve a JWT access token.
- Authentication Required: None (Public)
- Request Body:
{ "email": "student@college.edu", "password": "securepassword" } - Success Response (200 OK):
{ "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } - Error Responses:
400 Bad Request: Email or password not entered.401 Unauthorized: Incorrect email/password or email not found.
- Method:
GET - Route:
/users/me - Purpose: Get profile details for the authenticated user session.
- Authentication Required: Yes (Bearer Token - Any Role)
- Success Response (200 OK):
{ "_id": "60d000000000000000000001", "name": "Jane Doe", "email": "jane@college.edu", "phoneNumber": "1234567890", "role": "student", "createdAt": "2026-08-16T10:00:00.000Z", "updatedAt": "2026-08-16T10:00:00.000Z" } - Error Responses:
401 Unauthorized: Missing/invalid token.404 Not Found: User data not found.
- Method:
GET - Route:
/users/getStats - Purpose: Get count statistics for registered users in the database.
- Authentication Required: Yes (Bearer Token - Guard or Admin)
- Success Response (200 OK - Admin view):
{ "userCount": 42, "studentCount": 30, "guardCount": 4, "wardenCount": 7 } - Success Response (200 OK - Warden view): Returns a raw number representing the total student count.
30
- Method:
GET - Route:
/users/:id - Purpose: Get general profile details by user ObjectID.
- Authentication Required: Yes (Bearer Token - Any Role; Students can only query their own ID)
- Success Response (200 OK):
{ "_id": "60d000000000000000000001", "name": "Jane Doe", "email": "jane@college.edu", "phoneNumber": "1234567890", "role": "student" } - Error Responses:
403 Forbidden: Access denied (if student queries another user ID).404 Not Found: User not found.
- Method:
GET - Route:
/student/me - Purpose: Retrieve specific academic profile details for the authenticated student.
- Authentication Required: Yes (Bearer Token - Student)
- Success Response (200 OK):
{ "_id": "60d000000000000000000005", "userId": "60d000000000000000000001", "rollNumber": "CS202609", "branch": "Computer Science", "hostel": "Block A", "roomNumber": 204, "createdAt": "2026-08-16T10:00:00.000Z", "updatedAt": "2026-08-16T10:00:00.000Z" }
- Method:
GET - Route:
/student/:id - Purpose: Retrieve academic details by base User ObjectID.
- Authentication Required: Yes (Bearer Token - Any Role; Students can only query their own ID)
- Success Response (200 OK): Same structure as
/student/me. - Error Responses:
403 Forbidden: Access denied.404 Not Found: Student not found.
- Method:
POST - Route:
/outpass/createOutpass - Purpose: Submit a new outpass permission request.
- Authentication Required: Yes (Bearer Token - Student)
- Request Body:
{ "purpose": "Medical checkup", "location": "City General Hospital", "fromTime": "2026-08-16T16:00:00.000Z", "toTime": "2026-08-16T20:00:00.000Z" } - Success Response (201 Created):
{ "message": "Outpass Created successfully", "outPass": { "_id": "60d000000000000000000100", "requestedBy": "60d000000000000000000001", "purpose": "Medical checkup", "location": "City General Hospital", "fromTime": "2026-08-16T16:00:00.000Z", "toTime": "2026-08-16T20:00:00.000Z", "status": "Pending", "createdAt": "2026-08-16T15:45:00.000Z" } }
- Method:
GET - Route:
/outpass/getOutpasses - Purpose: Retrieve all outpasses requested by the logged student.
- Authentication Required: Yes (Bearer Token - Student)
- Success Response (200 OK):
{ "message": "Outpasses fetched successfully", "outpasses": [ { "_id": "60d000000000000000000100", "purpose": "Medical checkup", "location": "City General Hospital", "fromTime": "2026-08-16T16:00:00.000Z", "toTime": "2026-08-16T20:00:00.000Z", "status": "Pending" } ] }
- Method:
GET - Route:
/outpass/getAllOutpasses - Purpose: Get all outpasses in the system for review.
- Authentication Required: Yes (Bearer Token - Warden or Admin)
- Success Response (200 OK):
{ "message": "Outpasses fetched successfully", "outPasses": [ ... ] }
- Method:
PATCH - Route:
/outpass/:id/status - Purpose: Approve or Reject a student outpass. Approving generates the secure QR token.
- Authentication Required: Yes (Bearer Token - Warden)
- Request Body:
{ "status": "Approved" } - (Allowed values:
"Approved","Rejected") - Success Response (200 OK):
{ "message": "Outpass updated successfully", "outpass": { "_id": "60d000000000000000000100", "status": "Approved", "eventTime": "2026-08-16T15:50:00.000Z", "eventBy": "60d000000000000000000002", "qrToken": "a3b98c5f6e2d1a8c0f7b4e5d6c8b9a2f" } }
- Method:
GET - Route:
/outpass/getStats - Purpose: Get statistical counts for each outpass status.
- Authentication Required: Yes (Bearer Token - Warden or Admin)
- Success Response (200 OK):
{ "total": 120, "approved": 85, "rejected": 15, "pending": 5, "expired": 10, "completed": 5 }
- Method:
GET - Route:
/log/movementStats - Purpose: Retrieve metrics detailing the count of students currently inside vs outside.
- Authentication Required: Yes (Bearer Token - Warden or Admin)
- Success Response (200 OK):
{ "outCount": 0, "inCount": 30 }
- Method:
GET - Route:
/outpass/verify/:token - Purpose: Scan a student outpass. It registers an
EXITlog on the first scan, and anENTRYlog on the second scan (which completes the outpass). - Authentication Required: Yes (Bearer Token - Guard)
- Success Response (200 OK - Exit scan):
{ "message": "EXIT recorded", "outpass": { "_id": "60d000000000000000000100", "status": "Approved", "qrToken": "a3b98c5f6e2d1a8c0f7b4e5d6c8b9a2f" } } - Success Response (200 OK - Entry scan):
{ "message": "ENTRY recorded", "outpass": { "_id": "60d000000000000000000100", "status": "Completed", "qrToken": "a3b98c5f6e2d1a8c0f7b4e5d6c8b9a2f" } } - Error Responses:
400 Bad Request: Token not passed / Invalid QR / Outpass already used / Expired / Not approved.403 Forbidden: Guard not found.
- Method:
POST - Route:
/users/createUser - Purpose: Create a base user profile. Returns user payload with ID.
- Authentication Required: Yes (Bearer Token - Admin)
- Request Body:
{ "name": "Alex Warden", "email": "alex@college.edu", "password": "password123", "phoneNumber": "9876543210", "role": "warden" } - Success Response (201 Created):
{ "message": "User created successfully", "user": { "id": "60d000000000000000000002", "name": "Alex Warden", "email": "alex@college.edu", "phoneNumber": "9876543210", "role": "warden" } }
- Method:
POST - Route:
/users/createWarden - Purpose: Link Warden metadata to an existing base user.
- Authentication Required: Yes (Bearer Token - Admin)
- Request Body:
{ "userId": "60d000000000000000000002", "S_ID": "W-909", "designation": "Assistant Warden", "block": "Block A" }
- Method:
POST - Route:
/users/createStudent - Purpose: Link Student metadata to an existing base user.
- Authentication Required: Yes (Bearer Token - Admin)
- Request Body:
{ "userId": "60d000000000000000000001", "rollNumber": "CS202609", "branch": "Computer Science", "hostel": "Block A", "roomNumber": 204 }
- Method:
POST - Route:
/users/createGuard - Purpose: Link Security Guard metadata to an existing base user.
- Authentication Required: Yes (Bearer Token - Admin)
- Request Body:
{ "userId": "60d000000000000000000003", "S_ID": "G-505", "gate": "Main Gate 1" }
- Method:
GET - Route:
/admin/stats - Purpose: Aggregates User metrics, Outpass stats, and Movement stats into a single payload.
- Authentication Required: Yes (Bearer Token - Admin)
- Success Response (200 OK):
{ "userStats": { "userCount": 42, "studentCount": 30, "guardCount": 4, "wardenCount": 7 }, "outpassStats": { "total": 120, "approved": 85, "rejected": 15, "pending": 5, "expired": 10, "completed": 5 }, "movementStats": { "outCount": 0, "inCount": 30 } }