Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheSerchCp/SEAM-API/llms.txt

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

This guide walks you through getting SEAM API running locally — from cloning the repository to making your first authenticated HTTP request with a real JWT token. By the end you will have a working server, a registered user, and a valid token you can use to explore every protected endpoint.
1

Clone the repo and install dependencies

Clone the SEAM API repository and install all production and development dependencies with a single command:
git clone https://github.com/TheSerchCp/SEAM-API.git
cd SEAM-API
npm install
npm install pulls every package listed in package.json, including nodemon as a dev dependency for automatic server restarts during development. You do not need to install anything globally.
Node.js 18 or later is recommended. SEAM API uses AsyncLocalStorage (available since Node 12.17) and Express 5, which requires Node 18+.
2

Create the .env file

SEAM API validates required environment variables at startup and throws immediately if any are missing. Create a .env file at the project root before starting the server:
# .env — place this file at the root of the project (next to package.json)

# Server
PORT=3000

# MySQL database connection
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_NAME=seam_db

# JWT
JWT_SECRET=replace_with_a_long_random_string
JWT_EXPIRES_IN=1h

# CORS — set to your frontend origin in production
CORS_ORIGIN=http://localhost:5173
The variables PORT, DB_HOST, DB_USER, DB_PASSWORD, DB_NAME, and JWT_SECRET are required — the server will refuse to start without them. DB_PORT, JWT_EXPIRES_IN, and CORS_ORIGIN are optional and fall back to the defaults shown above.See the Configuration page for the full description of every variable, allowed values, and validation rules.
3

Start the server

Use the dev script during local development. It starts the server with nodemon, which watches for file changes and restarts automatically:
npm run dev
For a production environment where you want the Node.js process to run without the file watcher overhead, use:
npm start
A successful startup prints the following to stdout:
🚀 Servidor corriendo en http://localhost:3000/api/v1
If a required environment variable is missing you will instead see:
Error: Variable de entorno requerida faltante: JWT_SECRET
Fix the .env file and restart.
4

Register a user

With the server running, send a POST request to /api/v1/auth/register to create your first user. The roleId field assigns the user to an existing role in your database:
curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"full_name": "John Doe", "email": "john@example.com", "password": "secret123", "roleId": 1}'
A successful registration returns HTTP 201 Created with the new user’s data:
{
  "success": true,
  "message": "Usuario registrado exitosamente",
  "data": {
    "idUser": 1,
    "full_name": "John Doe",
    "email": "john@example.com",
    "roleId": 1
  }
}
The password is hashed with bcrypt before being stored — it is never saved in plaintext and is never returned in any response.
5

Log in and retrieve your token

Send a POST request to /api/v1/auth/login with the credentials you just registered:
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "password": "secret123"}'
The login response includes the JWT, its expiry, the user object, the role-filtered sidebar items, and the permissions assigned to the user’s role:
{
  "success": true,
  "message": "Login exitoso",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "1h",
    "user": {
      "idUser": 1,
      "full_name": "John Doe",
      "email": "john@example.com",
      "roleId": 1,
      "roleName": "admin"
    },
    "sidebarItems": [
      { "idItem": 1, "nameItem": "Dashboard", "iconItem": "home", "route": "/dashboard" }
    ],
    "permissions": [
      "GET /api/v1/users",
      "POST /api/v1/roles"
    ]
  }
}
Copy the value of token — you will pass it in the Authorization header for every subsequent request to a protected endpoint.
6

Make an authenticated request

Pass the token in the Authorization: Bearer header to call any protected endpoint. The following example retrieves the full list of users:
curl http://localhost:3000/api/v1/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
A successful response returns HTTP 200 OK with the users array:
{
  "success": true,
  "message": "OK",
  "data": [
    {
      "idUser": 1,
      "full_name": "John Doe",
      "email": "john@example.com",
      "roleId": 1
    }
  ]
}
If the token is missing, expired, or malformed, the API returns 401 Unauthorized. If the token is valid but the user’s role does not have permission for the requested URI, the API returns 403 Forbidden.
Real-time progress tracking with X-Socket-ID — Once your frontend establishes a Socket.IO connection (authenticated with the same JWT), include the socket’s ID in every mutating request using the X-Socket-ID header:
curl -X PUT http://localhost:3000/api/v1/users/1 \
  -H "Authorization: Bearer <token>" \
  -H "X-Socket-ID: abc123socketid" \
  -H "Content-Type: application/json" \
  -d '{"full_name": "Jane Doe"}'
The server reads X-Socket-ID from the request context and uses it to emit operation:progress events (start → processing → success / error) directly to the exact browser tab that triggered the operation, enabling precise loading-state control on the client.

Build docs developers (and LLMs) love

Get started for freeTalk to us