Voter Survey API Documentation

Live

RESTful backend service for managing voters and survey users. It uses JWT-based authentication and role-based access control.

What is this?

This service powers a voter survey system. There is a single Admin who can create survey Users and assign them one or more ward numbers. Users can query voters only for their assigned wards.

Note: Tokens are returned via httpOnly cookies and also included in the JSON response. You can authenticate by cookie or send the token in an Authorization: Bearer <token> header.

Authentication & Roles

  • JWT is signed with JWT_SECRET and expires in 1 day.
  • Admin token payload includes: { role: "admin", userId }.
  • User token payload includes: { role: "user", userId, ward: number[] }.

/api/auth

POST /api/auth/admin/login Admin
Logs in the Admin using credentials stored server-side. Sets a cookie and returns a token.

Request Body

{
  "userId": "adminId",
  "password": "adminPassword"
}

Response

{
  "message": "Admin logged in successfully",
  "token": "<jwt_token>"
}
POST /api/auth/admin/logout Admin
Clears the authentication cookie.

Response

{
  "message": "Admin logged out successfully"
}
POST /api/auth/user/login User
Logs in a User. The token payload contains the assigned ward array.

Request Body

{
  "userId": "demoUser",
  "password": "userPassword"
}

Response

{
  "message": "User logged in successfully",
  "token": "<jwt_token>"
}
POST /api/auth/user/logout User
Clears the user authentication cookie.

Response

{
  "message": "User logged out successfully"
}

/api/admin Protected: Admin

POST /api/admin/user-register
Creates a new survey user and assigns wards.

Request Body

{
  "name": "John Doe",
  "userId": "johndoe",
  "contact": "1234567890",
  "password": "securePass123",
  "ward": [5, 7, 10]
}

Response

{
  "message": "User registered successfully",
  "user": {
    "name": "John Doe",
    "userId": "johndoe",
    "password": "securePass123"
  }
}
POST /api/admin/user-delete/:userId
Deletes a user by their userId.

Response

{
  "message": "User deleted successfully"
}
GET /api/admin/users
Returns all registered users.

Response

[{
  "_id": "64f3...",
  "name": "John Doe",
  "userId": "johndoe",
  "contact": "1234567890",
  "ward": [5, 7, 10]
}]
GET /api/admin/voters
Returns all voters.

Response

[{
  "_id": "64f4...",
  "Name": "Jane Smith",
  "Ward_Number": 5
}]

/api/user Protected: User

GET /api/user/
Returns voters for the logged-in user's assigned wards (uses $in on Ward_Number).

Example Response

[{
  "_id": "64f5...",
  "Name": "Alice Johnson",
  "Ward_Number": 5
}, {
  "_id": "64f6...",
  "Name": "Bob Brown",
  "Ward_Number": 7
}]

Middlewares

  • verifyToken: Reads JWT from cookie or Authorization header and attaches payload to req.user.
  • isAdmin: Ensures req.user.role === "admin".
All /api/admin routes apply both verifyToken and isAdmin. All /api/user routes apply verifyToken.

Deployment Notes

  • Deployed on Render: https://voter-survery.onrender.com
  • Cookies set with httpOnly and secure (NODE_ENV==="production").
  • You can also authenticate using Authorization: Bearer <token>.