POST /api/v1/auth/login — Authenticate and Get JWT Token

The POST /api/v1/auth/login endpoint authenticates a registered user by verifying their email and password against the stored bcrypt hash. On success it returns a signed JSON Web Token, the token’s expiry duration, the user object (without password), sidebar navigation items for the user’s role, and a flat list of URI permission strings the role can access. No authentication token is required to call this endpoint.

Endpoint

POST /api/v1/auth/login

Base URL: http://localhost:{PORT}/api/v1 Authentication: None required

Request Body

string

required

The email address the user registered with.

password

string

required

The user’s plain-text password. It is compared against the stored bcrypt hash using bcrypt.compare.

Example Request

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "password": "securePass123"
  }'

Responses

200 OK

Returned when credentials are valid. The response includes the JWT token, its expiry, the authenticated user, role-based sidebar items, and the full list of nameUri permission strings for the user’s role.

{
  "success": true,
  "message": "Login exitoso",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZFVzZXIiOjcsImVtYWlsIjoiamFuZS5kb2VAZXhhbXBsZS5jb20iLCJyb2xlSWQiOjIsInJvbGVOYW1lIjoiZWRpdG9yIiwiaWF0IjoxNzE5MDAwMDAwLCJleHAiOjE3MTkwMDM2MDB9.abc123",
    "expiresIn": "1h",
    "user": {
      "idUser": 7,
      "full_name": "Jane Doe",
      "email": "jane.doe@example.com",
      "roleId": 2,
      "roleName": "editor"
    },
    "sidebarItems": [
      {
        "idItem": 1,
        "nameItem": "Dashboard",
        "iconItem": "home",
        "route": "/dashboard"
      },
      {
        "idItem": 3,
        "nameItem": "Users",
        "iconItem": "users",
        "route": "/users"
      }
    ],
    "permissions": [
      "GET /api/v1/users",
      "GET /api/v1/users/:id",
      "PUT /api/v1/users/:id"
    ]
  }
}

success

boolean

Always true for successful responses.

message

string

Human-readable confirmation message: "Login exitoso".

data

object

The full authentication payload.

Show data fields

data.token

string

A signed JWT string. Include this in the Authorization header of every protected request as Bearer <token>.

data.expiresIn

string

Token validity duration sourced from the JWT_EXPIRES_IN environment variable (e.g., "1h", "7d").

data.user

object

The authenticated user record. The password field is always omitted.

Show user fields

data.user.idUser

number

Unique numeric identifier for the user.

data.user.full_name

string

User’s full display name.

data.user.email

string

User’s registered email address.

data.user.roleId

number

Numeric ID of the role assigned to the user.

data.user.roleName

string

Human-readable name of the role (joined from the roles table).

data.sidebarItems

array

Ordered list of navigation items the user’s role is permitted to see in the frontend sidebar. Each item is sourced from the sidebarItems table via the roleXItem pivot.

Show sidebarItems fields

data.sidebarItems[].idItem

number

Primary key of the sidebar item.

data.sidebarItems[].nameItem

string

Display label for the navigation entry.

data.sidebarItems[].iconItem

string

Icon identifier string used by the frontend icon library.

data.sidebarItems[].route

string

Frontend route path the navigation item links to.

data.permissions

array of strings

Flat array of nameUri strings representing every API route the user’s role can call (e.g., "GET /api/v1/users", "PUT /api/v1/users/:id"). Sourced from the permissions table via the permissionXRole pivot.

400 Bad Request — Validation Error

Returned when email or password fields are missing or fail type validation enforced by validate.middleware against loginSchema.

{
  "success": false,
  "message": "El campo 'email' es requerido",
  "data": null
}

401 Unauthorized — Invalid Credentials

Returned when no user exists with the provided email, or the password does not match the stored bcrypt hash. The service throws UnauthorizedError('Credenciales inválidas').

{
  "success": false,
  "message": "Credenciales inválidas",
  "data": null
}

JWT Payload

The token is signed with HS256 (default for jsonwebtoken). After verification, the decoded payload contains:

Field	Type	Description
`idUser`	number	User’s primary key
`email`	string	User’s email address
`roleId`	number	Numeric role ID
`roleName`	string	Role name string
`iat`	number	Issued-at timestamp (Unix seconds)
`exp`	number	Expiration timestamp (Unix seconds)

Socket.IO Events

During login the service emits real-time progress events on the auth:login channel:

Order	Status	Payload message
1	`start`	`"Iniciando autenticación..."`
2	`processing`	`"Verificando credenciales..."`
3	`processing`	`"Cargando permisos y menú..."`
4	`processing`	`"Generando token de sesión..."`
5	`success`	`"Sesión iniciada exitosamente"`

// Client-side listener example
socket.on("auth:login", (event) => {
  console.log(event.status, event.message);
  // { status: "success", message: "Sesión iniciada exitosamente" }
});

Store the token value in a secure location (e.g., an httpOnly cookie or a secure in-memory store — avoid localStorage in sensitive applications). Include it in all subsequent protected API requests via the Authorization header:

Authorization: Bearer <token>

Once the token expires (see expiresIn), the user must log in again to obtain a new one.

Auth

Users

Roles

Permissions

Sidebar

POST /api/v1/auth/login — Authenticate and Get JWT Token

Endpoint

Request Body

Example Request

Responses

200 OK

400 Bad Request — Validation Error

401 Unauthorized — Invalid Credentials

JWT Payload

Socket.IO Events

Build docs developers (and LLMs) love

Auth

Users

Roles

Permissions

Sidebar

Documentation Index

​Endpoint

​Request Body

​Example Request

​Responses

​200 OK

​400 Bad Request — Validation Error

​401 Unauthorized — Invalid Credentials

​JWT Payload

​Socket.IO Events

Build docs developers (and LLMs) love

Endpoint

Request Body

Example Request

Responses

200 OK

400 Bad Request — Validation Error

401 Unauthorized — Invalid Credentials

JWT Payload

Socket.IO Events