Skip to main content

​
Overview

The E-commerce API uses JWT (JSON Web Tokens) for authentication. After successful login, you receive a token that must be included in subsequent requests to protected endpoints.

​
Authentication Flow

  1. Register a new user or login with existing credentials
  2. Receive a JWT token in the response
  3. Include the token in the Authorization header for protected requests
  4. Token expires after the configured duration (default: 1 hour)

​
Authentication Endpoints

​
Register New User

Create a new customer account. 
POST /auth/register
Content-Type: application/json
Request Body: 
{
  "name": "John Doe",
  "email": "[email protected]",
  "password": "securePassword123"
}
Validation Rules:
  • name: Required string
  • email: Valid email format
  • password: Minimum 6 characters
Response (201 Created): 
{
  "message": "Usuario registrado exitosamente",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "role": "customer",
    "createdAt": "2026-03-06T10:30:00Z"
  }
}

​
Login

Authenticate and receive a JWT token. 
POST /auth/login
Content-Type: application/json
Request Body: 
{
  "email": "[email protected]",
  "password": "securePassword123"
}
Response (200 OK): 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "role": "customer"
  }
}

​
Create User with Role (Admin Only)

Administrators can create users with specific roles. 
POST /auth/create-user
Authorization: Bearer <admin-token>
Content-Type: application/json
Request Body: 
{
  "name": "Admin User",
  "email": "[email protected]",
  "password": "securePassword123",
  "role": "admin"
}
Valid Roles:
  • customer
  • admin
Response (201 Created): 
{
  "message": "Usuario creado exitosamente",
  "user": {
    "id": 2,
    "name": "Admin User",
    "email": "[email protected]",
    "role": "admin",
    "createdAt": "2026-03-06T10:35:00Z"
  }
}

​
Update Profile

Update authenticated user’s profile information. 
PUT /auth/profile
Authorization: Bearer <token>
Content-Type: application/json
Request Body: 
{
  "name": "John Smith",
  "email": "[email protected]"
}
Both fields are optional. Include only the fields you want to update. Response (200 OK): 
{
  "id": 1,
  "name": "John Smith",
  "email": "[email protected]",
  "role": "customer",
  "createdAt": "2026-03-06T10:30:00Z"
}

​
Delete Account

Delete the authenticated user’s account. 
DELETE /auth/delete
Authorization: Bearer <token>
Response (200 OK): 
{
  "message": "Usuario eliminado exitosamente",
  "user": {
    "id": 1,
    "email": "[email protected]"
  }
}

​
Using JWT Tokens

​
Token Structure

JWT tokens contain the following payload: 
{
  id: number,        // User ID
  email: string,     // User email
  role: "customer" | "admin",  // User role
  iat: number,       // Issued at timestamp
  exp: number        // Expiration timestamp
}
Reference: /workspace/source/backend/src/utils/jwt.ts:8-12

​
Including Tokens in Requests

Add the token to the Authorization header using the Bearer scheme: 
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/auth/profile
JavaScript Example: 
fetch('http://localhost:3000/auth/profile', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})
Python Example: 
import requests

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

response = requests.get('http://localhost:3000/auth/profile', headers=headers)

​
Token Expiration

Tokens expire after a configured duration (default: 1 hour). The expiration time is controlled by the JWT_EXPIRY environment variable. When a token expires, you’ll receive a 401 Unauthorized response: 
{
  "error": "Invalid token"
}
You must login again to obtain a new token.

​
Authentication Middleware

The authentication middleware validates tokens and extracts user information: 
// From: /workspace/source/backend/src/middleware/auth.middleware.ts:7-22
export function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  const token = authHeader?.split(" ")[1];

  if (!token) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  try {
    const payload = verifyToken(token);
    req.user = payload; // User info available in request
    next();
  } catch {
    res.status(401).json({ error: "Invalid token" });
  }
}

​
Security Best Practices

​
Token Storage

  • Never store tokens in localStorage (vulnerable to XSS)
  • Use httpOnly cookies for web applications
  • Store in secure storage on mobile apps

​
Token Transmission

  • Always use HTTPS in production
  • Never send tokens in URL parameters
  • Use the Authorization header

​
Token Security

  • Keep JWT_SECRET environment variable secure and complex
  • Rotate secrets periodically
  • Use appropriate expiration times (shorter is more secure)

​
Common Authentication Errors

StatusErrorCause
401”Unauthorized”No token provided
401”Invalid token”Token is malformed, expired, or invalid
403”Forbidden”Valid token but insufficient permissions
409”Resource already exists”Email already registered
422Validation errorInvalid input data format
See Error Handling for complete error documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us