Authentication

Overview

SmartShelf API uses JSON Web Tokens (JWT) for secure, stateless authentication. Tokens are issued upon successful registration or login and must be included in subsequent requests to protected endpoints.

Authentication Flow

Registration

Create a new user account.

Endpoint

POST /api/auth/register

Request Body

name

string

required

User’s full name

string

required

Valid email address (stored in lowercase)

password

string

required

Password (minimum 6 characters)

role

string

User role: Admin, Manager, or Worker (defaults to Worker)

Example Request

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "securepass123",
    "role": "Manager"
  }'

Response

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "[email protected]",
      "role": "Manager",
      "isActive": true,
      "createdAt": "2026-03-03T10:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSIsImlhdCI6MTcwOTQ2MTIwMCwiZXhwIjoxNzEwMDY2MDAwfQ.example"
  }
}

The token is also automatically set as an HttpOnly cookie named token for browser-based clients.

Authenticate with existing credentials.

Endpoint

POST /api/auth/login

Request Body

string

required

User’s email address

password

string

required

User’s password

Example Request

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepass123"
  }'

Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "[email protected]",
      "role": "Manager",
      "isActive": true
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Token Format and Usage

JWT Structure

Tokens are generated using the jsonwebtoken library with the following payload:

// src/utils/jwtHelper.js:4-11
{
  id: userId,
  iat: 1709461200,  // Issued at timestamp
  exp: 1710066000   // Expiration timestamp (default: 7 days)
}

Token Expiration

Default expiration: 7 days
Configurable via: JWT_EXPIRE environment variable
Cookie expiration: Matches JWT expiration (configurable via JWT_COOKIE_EXPIRE)

Authorization Header Format

Include the token in the Authorization header of protected requests:

Authorization: Bearer <your_jwt_token>

Example Authenticated Request

curl http://localhost:5000/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Alternatively, the API accepts tokens from HttpOnly cookies:

curl http://localhost:5000/api/auth/me \
  --cookie "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The protect middleware checks both the Authorization header and cookies (src/middlewares/authMiddleware.js:6-17).

Protected Routes

All protected endpoints require a valid JWT token. The authentication middleware:

Extracts token from cookies or Authorization header
Verifies token signature using JWT_SECRET
Checks if user exists and is active
Attaches user object to req.user

Get Current User

GET /api/auth/me

Returns the authenticated user’s profile.

Update Profile

PUT /api/auth/profile

Update name or email. Request Body:

{
  "name": "Jane Doe",
  "email": "[email protected]"
}

Change Password

PUT /api/auth/change-password

Request Body:

{
  "currentPassword": "oldpass123",
  "newPassword": "newpass456"
}

Logout

POST /api/auth/logout

Clears the authentication cookie.

Role-Based Access Control (RBAC)

SmartShelf implements three user roles with different permission levels:

Admin
Manager
Worker

Full system access

Manage all users
Configure system settings
Access all inventory and analytics
Create/delete resources

Authorization Middleware

The authorize middleware restricts endpoints by role:

// src/middlewares/authMiddleware.js:51-67
const { protect, authorize } = require('../middlewares/authMiddleware');

// Require Admin role
router.delete('/users/:id', protect, authorize('Admin'), deleteUser);

// Allow Admin or Manager
router.post('/tasks', protect, authorize('Admin', 'Manager'), createTask);

Example: Role Check Error

If a Worker attempts to access an Admin-only endpoint:

{
  "success": false,
  "message": "User role 'Worker' is not authorized to access this route"
}

Authentication Errors

Missing Token

{
  "success": false,
  "message": "Not authorized to access this route. Please login."
}

Invalid or Expired Token

{
  "success": false,
  "message": "Not authorized. Invalid or expired token."
}

Deactivated Account

If the user’s isActive flag is false:

{
  "success": false,
  "message": "Your account has been deactivated. Please contact admin."
}

Invalid Credentials

{
  "success": false,
  "message": "Invalid email or password"
}

Email Already Exists

{
  "success": false,
  "message": "User with this email already exists"
}

Security Best Practices

Store tokens securely

Use HttpOnly cookies in browser environments to prevent XSS attacks
Store tokens in secure storage (not localStorage) on mobile/desktop apps
Never expose tokens in URLs or logs

Handle token expiration

Implement automatic logout on token expiration
Consider implementing refresh token flow for long-lived sessions
Display clear error messages when tokens expire

Use HTTPS in production

Always use HTTPS to encrypt tokens in transit
Set secure: true in cookie options (controlled by NODE_ENV)
Configure proper CORS origins

Password requirements

Minimum 6 characters (enforced by API)
Passwords are hashed using bcryptjs with salt
Never log or display passwords in plain text

Account security

Change passwords regularly using /api/auth/change-password
Monitor for unauthorized access attempts
Admins can deactivate compromised accounts

Environment Variables

Required authentication configuration:

JWT_SECRET=your_secret_key_here
JWT_EXPIRE=7d
JWT_COOKIE_EXPIRE=7
NODE_ENV=production

Never commit your JWT_SECRET to version control. Use strong, randomly generated secrets in production.

Implementation Reference

Key files implementing authentication:

Controller: src/controllers/authController.js - Handles registration, login, logout
Middleware: src/middlewares/authMiddleware.js - Token verification and role authorization
Helper: src/utils/jwtHelper.js - Token generation and verification
Model: src/models/User.js - User schema with password hashing

Overview

Endpoints

Overview

Authentication Flow

Registration

Endpoint

Request Body

Example Request

Response

Endpoint

Request Body

Example Request

Response

Token Format and Usage

JWT Structure

Token Expiration

Authorization Header Format

Example Authenticated Request

Protected Routes

Get Current User

Update Profile

Change Password

Logout

Role-Based Access Control (RBAC)

Authorization Middleware

Example: Role Check Error

Authentication Errors

Missing Token

Invalid or Expired Token

Deactivated Account

Invalid Credentials

Email Already Exists

Security Best Practices

Environment Variables

Implementation Reference

Next Steps

API Overview

User Management

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Authentication Flow

​Registration

​Endpoint

​Request Body

​Example Request

​Response

​Login

​Endpoint

​Request Body

​Example Request

​Response

​Token Format and Usage

​JWT Structure

​Token Expiration

​Authorization Header Format

​Example Authenticated Request

​Cookie-Based Authentication

​Protected Routes

​Get Current User

​Update Profile

​Change Password

​Logout

​Role-Based Access Control (RBAC)

​Authorization Middleware

​Example: Role Check Error

​Authentication Errors

​Missing Token

​Invalid or Expired Token

​Deactivated Account

​Invalid Credentials

​Email Already Exists

​Security Best Practices

​Environment Variables

​Implementation Reference

​Next Steps

API Overview

User Management

Build docs developers (and LLMs) love

Overview

Authentication Flow

Registration

Endpoint

Request Body

Example Request

Response

Login

Endpoint

Request Body

Example Request

Response

Token Format and Usage

JWT Structure

Token Expiration

Authorization Header Format

Example Authenticated Request

Cookie-Based Authentication

Protected Routes

Get Current User

Update Profile

Change Password

Logout

Role-Based Access Control (RBAC)

Authorization Middleware

Example: Role Check Error

Authentication Errors

Missing Token

Invalid or Expired Token

Deactivated Account

Invalid Credentials

Email Already Exists

Security Best Practices

Environment Variables

Implementation Reference

Next Steps