Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Eleazarguitar18/kantuta_pos_back/llms.txt

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

The /auth resource is the gateway to the Kantuta POS Backend. It issues short-lived JWT access tokens and long-lived refresh tokens that your client stores and rotates automatically. The password reset flow is a three-step sequence: request a one-time code by email, verify the code, then submit the new password. Administrative CRUD operations on auth accounts (list, fetch, update, soft-delete) are also exposed under this resource and require a valid Bearer token.
All endpoints in this section are available at the base URL http://localhost:3000. Substitute the production URL as needed.

POST /auth/login

PUBLIC Authenticates a user with email and password. Returns a short-lived access_token, a long-lived refresh_token, and the full Usuario object including the linked Persona and assigned Role.

Request body

email
string
required
The user’s registered email address. Must be a valid email format — e.g. [email protected].
password
string
required
The user’s password as plain text. Transmitted over HTTPS; hashed server-side with bcrypt.

Response

access_token
string
Short-lived JWT used to authenticate subsequent requests via Authorization: Bearer <access_token>.
refresh_token
string
Long-lived JWT used exclusively with POST /auth/refresh_token to obtain a new access token when the current one expires.
user
Usuario
The authenticated user record, including nested persona (personal profile) and role objects. See the Usuario interface below.
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "MiClave123!"
  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "name": "Admin Kantuta",
    "email": "[email protected]",
    "estado": true,
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z",
    "persona": {
      "id": 1,
      "nombres": "Carlos",
      "p_apellido": "Flores",
      "s_apellido": "Mamani",
      "fecha_nacimiento": "1990-06-15",
      "genero": "M",
      "estado": true,
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:00:00.000Z"
    },
    "role": {
      "id": 1,
      "nombre": "admin",
      "descripcion": "Administrador del sistema"
    }
  }
}

POST /auth/refresh_token

PUBLIC Issues a new access_token using a valid refresh_token. The refresh token is passed in the Authorization header — not in the request body. This endpoint does not issue a new refresh token; rotate your refresh tokens by re-logging in.
Pass the refresh token (not the access token) in the Authorization header for this endpoint. Using an expired or invalid refresh token returns 401 Unauthorized.

Request headers

Authorization
string
required
Must be Bearer <refresh_token> — the long-lived token received at login.

Response

access_token
string
A fresh, short-lived JWT to replace the expired access token.
curl -X POST http://localhost:3000/auth/refresh_token \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /auth/reset/code

PUBLIC Step 1 of the password reset flow. Sends a 6-character alphanumeric code to the provided email address. The code is valid for 15 minutes. After receiving the code, proceed to POST /auth/confirm-code.
The code is generated server-side and stored temporarily. It is case-sensitive and expires automatically after 15 minutes. Request a new code if it expires.

Request body

email
string
required
The email address associated with the account that needs a password reset.

Response

message
string
Confirmation string, e.g. "Código de verificación enviado al correo".
curl -X POST http://localhost:3000/auth/reset/code \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
{
  "message": "Código de verificación enviado al correo"
}

POST /auth/confirm-code

PUBLIC Step 2 of the password reset flow. Verifies that the 6-character code sent by email is valid and has not expired. A successful response allows the client to proceed to POST /auth/reset-confirm.

Request body

email
string
required
The email address for which the reset code was requested.
code
string
required
The 6-character alphanumeric code received via email — e.g. A1B2C3. Case-sensitive.

Response

message
string
Confirmation string, e.g. "Código de verificación correcto".
curl -X POST http://localhost:3000/auth/confirm-code \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "code": "A1B2C3"
  }'
{
  "message": "Código de verificación correcto"
}

POST /auth/reset-confirm

PUBLIC Step 3 and final step of the password reset flow. Sets a new password for the account after a valid code has been confirmed. Call this only after POST /auth/confirm-code succeeds.

Request body

email
string
required
The email address of the account being reset.
newPassword
string
required
The new plain-text password. Hashed server-side before storage. Choose a strong password.

Response

message
string
Confirmation string, e.g. "Contraseña actualizada correctamente".
curl -X POST http://localhost:3000/auth/reset-confirm \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "newPassword": "NuevaClave456!"
  }'
{
  "message": "Contraseña actualizada correctamente"
}

POST /auth/change-password

PROTECTED Changes the password of any user account directly. This endpoint is for authenticated administrators — it does not require the 3-step reset flow. Requires a valid Bearer access token.

Request headers

Authorization
string
required
Bearer <access_token> — obtained from POST /auth/login.

Request body

email
string
required
The email address of the account whose password is being changed.
newPassword
string
required
The new password in plain text. Will be hashed server-side before storage.

Response

message
string
Confirmation string on success.
curl -X POST http://localhost:3000/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "email": "[email protected]",
    "newPassword": "OtraClave789!"
  }'
{
  "message": "Contraseña cambiada correctamente"
}

GET /auth/roles/list

PROTECTED Returns all available roles defined in the system. Used when assigning roles to new or existing user accounts.

Request headers

Authorization
string
required
Bearer <access_token>.

Response

Returns an array of Role objects.
id
number
Unique role identifier.
nombre
string
Role name. Typical values: "admin", "lider", "user".
descripcion
string
Optional human-readable description of the role’s permissions.
curl -X GET http://localhost:3000/auth/roles/list \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
[
  { "id": 1, "nombre": "admin", "descripcion": "Administrador del sistema" },
  { "id": 2, "nombre": "lider", "descripcion": "Líder de turno" },
  { "id": 3, "nombre": "user", "descripcion": "Cajero estándar" }
]

GET /auth

PROTECTED Returns all auth user account records. Used for administrative account management.

Request headers

Authorization
string
required
Bearer <access_token>.
curl -X GET http://localhost:3000/auth \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

GET /auth/:id

PROTECTED Retrieves a single auth user account by its numeric ID.

Path parameters

id
number
required
The numeric ID of the auth account to retrieve.

Request headers

Authorization
string
required
Bearer <access_token>.
curl -X GET http://localhost:3000/auth/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

PATCH /auth/:id

PROTECTED Partially updates an auth account. All body fields are optional; only the fields provided will be updated.

Path parameters

id
number
required
The numeric ID of the auth account to update.

Request headers

Authorization
string
required
Bearer <access_token>.

Request body (UpdateAuthDto — all fields optional)

UpdateAuthDto extends CreateAuthDto via PartialType, so every field from registration is also accepted here as an optional update.
name
string
Display name for the account.
email
string
Updated email address. Must be unique across all accounts.
password
string
New password in plain text. Hashed server-side before storage.
estado
boolean
Account active/inactive flag.
nombres
string
Updated given name(s) for the linked Persona record.
p_apellido
string
Updated paternal surname for the linked Persona record.
s_apellido
string
Updated maternal surname for the linked Persona record.
fecha_nacimiento
string
Updated date of birth (YYYY-MM-DD) for the linked Persona record.
genero
string
Updated gender code ("M" or "F") for the linked Persona record.
id_role
number
ID of the role to assign to this account. See GET /auth/roles/list for available values.
curl -X PATCH http://localhost:3000/auth/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{"name": "Carlos Administrador"}'

DELETE /auth/:id

PROTECTED Soft-deletes an auth account by setting its estado field to false. The record remains in the database for audit purposes.
This is a soft delete. The account is deactivated, not permanently removed. Deactivated accounts cannot log in.

Path parameters

id
number
required
The numeric ID of the auth account to deactivate.

Request headers

Authorization
string
required
Bearer <access_token>.
curl -X DELETE http://localhost:3000/auth/5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Axios Integration (React + TypeScript)

The following setup creates an Axios instance that automatically injects the access token on every request and transparently refreshes it when a 401 response is received. Copy this into your frontend project (e.g. src/lib/api.ts).
import axios from 'axios';

// 1. Create the Axios instance
const api = axios.create({
  baseURL: 'http://localhost:3000',
  headers: {
    'Content-Type': 'application/json',
  },
});

// 2. Inject the access token on every outgoing request
api.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('access_token');
    if (token && config.headers) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error),
);

// 3. Auto-refresh the access token on 401 responses
api.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;
    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;
      try {
        const refreshToken = localStorage.getItem('refresh_token');

        // Call refresh endpoint directly (bypassing the request interceptor)
        const res = await axios.post(
          'http://localhost:3000/auth/refresh_token',
          {},
          { headers: { Authorization: `Bearer ${refreshToken}` } },
        );

        const newAccessToken: string = res.data.access_token;
        localStorage.setItem('access_token', newAccessToken);

        // Retry the original request with the new access token
        originalRequest.headers.Authorization = `Bearer ${newAccessToken}`;
        return api(originalRequest);
      } catch (refreshError) {
        // Refresh token also expired — force re-login
        localStorage.removeItem('access_token');
        localStorage.removeItem('refresh_token');
        window.location.href = '/login';
        return Promise.reject(refreshError);
      }
    }
    return Promise.reject(error);
  },
);

export default api;

Login helper

import api from './api';
import { Usuario } from './types';

interface LoginResponse {
  access_token: string;
  refresh_token: string;
  user: Usuario;
}

export async function login(email: string, password: string): Promise<LoginResponse> {
  const { data } = await api.post<LoginResponse>('/auth/login', { email, password });
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data;
}

TypeScript Interfaces

export interface Role {
  id: number;
  nombre: 'admin' | 'lider' | 'user' | string;
  descripcion?: string;
}

export interface BaseEntityAudit {
  estado: boolean;
  id_user_create: number | null;
  id_user_update?: number | null;
  created_at: string; // ISO 8601
  updated_at: string; // ISO 8601
}

export interface Persona extends BaseEntityAudit {
  id: number;
  nombres: string;
  p_apellido: string;
  s_apellido?: string;
  fecha_nacimiento: string; // YYYY-MM-DD
  genero: string;           // 'M' | 'F'
}

export interface Usuario extends BaseEntityAudit {
  id: number;
  name: string;
  email: string;
  persona: Persona;
  role: Role;
}

Build docs developers (and LLMs) love