Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/praveenarya123/sps-backend/llms.txt

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

The SPS School Backend uses JSON Web Tokens (JWT) for stateless authentication. Every protected endpoint requires a valid token issued at login. Role-based middleware further restricts access so that users can only reach endpoints appropriate to their role.

​
How authentication works

  1. The client registers a user account via POST /api/auth/register.
  2. The client logs in via POST /api/auth/login and receives a JWT.
  3. Every subsequent request to a protected route includes the raw token in the Authorization header.
  4. The auth middleware verifies the token and attaches the decoded payload (id, role) to req.user.
  5. Role middleware (where applied) checks req.user.role against the required role for the endpoint.

​
Register a user

POST /api/auth/register Creates a new user account. The password is hashed with bcrypt before storage.

​
Request body

​
name
string
required
Full name of the user.
​
email
string
required
Email address. Used as the login identifier.
​
password
string
required
Plaintext password. Stored as a bcrypt hash (saltRounds: 10).
​
role
string
required
One of the seven valid roles (see Roles below).

​
Example request

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bob Teacher",
    "email": "bob@school.edu",
    "password": "mypassword",
    "role": "TEACHER"
  }'

​
Response

{
  "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "name": "Bob Teacher",
  "email": "bob@school.edu",
  "password": "$2b$10$hashedvalue...",
  "role": "TEACHER",
  "__v": 0
}
​
_id
string
required
MongoDB-generated unique identifier for the user.
​
name
string
required
The name provided at registration.
​
email
string
required
The email address provided at registration.
​
password
string
required
The bcrypt hash of the password. Never the plaintext value.
​
role
string
required
The role assigned to this user.

​
Log in

POST /api/auth/login Validates credentials and returns a JWT for use in subsequent requests.

​
Request body

​
email
string
required
The user’s registered email address.
​
password
string
required
The user’s plaintext password.

​
Example request

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bob@school.edu",
    "password": "mypassword"
  }'

​
Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY0ZjFhMmIzYzRkNWU2ZjdhOGI5YzBkMSIsInJvbGUiOiJURUFDSEVSIiwiaWF0IjoxNjkzMDAwMDAwfQ.signature",
  "role": "TEACHER"
}
​
token
string
required
A signed JWT. Include this value in the Authorization header of every protected request.
​
role
string
required
The role of the authenticated user. Use this to determine which endpoints are accessible.

​
Login error responses

StatusConditionBody
404No user found with the given email{ "message": "User not found" }
400Email matched but password was incorrect{ "message": "Wrong password" }

​
Authenticating requests

Include the token in the Authorization header of every protected request. The middleware reads the header value directly as the raw token — not in Bearer <token> format.
Do not prefix the token with Bearer. The middleware reads req.headers.authorization directly. Sending Bearer eyJ... will cause jwt.verify to fail.

​
Example

curl -X POST http://localhost:5000/api/teacher/assignment \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"classId": 10, "title": "Algebra Homework", "dueDate": "2026-04-01T23:59:00.000Z"}'
The token is signed with JWT_SECRET from your .env file. It encodes the user’s id and role. The token does not expire by default — set an expiresIn option in jwt.sign if you need expiry.

​
Roles

Every user is assigned exactly one role at registration. Role middleware on protected routes compares req.user.role to the required role and rejects mismatches with 403.
RoleDescription
SUPER_ADMINFull system access across all domains
ACADEMIC_ADMINManages academic records and operations
STUDENT_ADMINManages student records
FINANCE_ADMINManages fees and financial records
OPERATIONS_ADMINHandles operational administration
TEACHERCreates assignments, approves student applications
STUDENTSubmits assignments, sends applications
Roles are case-sensitive. TEACHER is valid; Teacher or teacher will be rejected by role middleware.

​
Auth failure responses

​
401 Unauthorized — missing or invalid token

Returned by authMiddleware when the Authorization header is absent or the token fails jwt.verify. 
{
  "message": "Unauthorized"
}
Common causes:
  • The Authorization header was not included in the request.
  • The token was signed with a different JWT_SECRET than the server is currently using.
  • The token value is malformed.

​
403 Forbidden — insufficient role

Returned by roleMiddleware when the token is valid but the user’s role does not match the required role for the endpoint. 
{
  "message": "Access denied"
}
Common causes:
  • Calling a TEACHER-only endpoint with a STUDENT token.
  • Calling an admin endpoint with a non-admin role.

​
Full authenticated request example

This example shows the complete flow: log in, capture the token, then call a protected endpoint. 
# Step 1 — log in and capture the token
TOKEN=$(curl -s -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "bob@school.edu", "password": "mypassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Step 2 — call a protected endpoint (requires TEACHER role)
curl -X POST http://localhost:5000/api/teacher/assignment \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"classId": 10, "title": "Algebra Homework", "dueDate": "2026-04-01T23:59:00.000Z"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us