TheDocumentation 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.
/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-livedaccess_token, a long-lived refresh_token, and the full Usuario object including the linked Persona and assigned Role.
Request body
The user’s registered email address. Must be a valid email format — e.g.
[email protected].The user’s password as plain text. Transmitted over HTTPS; hashed server-side with bcrypt.
Response
Short-lived JWT used to authenticate subsequent requests via
Authorization: Bearer <access_token>.Long-lived JWT used exclusively with
POST /auth/refresh_token to obtain a new access token when the current one expires.The authenticated user record, including nested
persona (personal profile) and role objects. See the Usuario interface below.POST /auth/refresh_token
PUBLIC Issues a newaccess_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.
Request headers
Must be
Bearer <refresh_token> — the long-lived token received at login.Response
A fresh, short-lived JWT to replace the expired access token.
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 toPOST /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
The email address associated with the account that needs a password reset.
Response
Confirmation string, e.g.
"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 toPOST /auth/reset-confirm.
Request body
The email address for which the reset code was requested.
The 6-character alphanumeric code received via email — e.g.
A1B2C3. Case-sensitive.Response
Confirmation string, e.g.
"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 afterPOST /auth/confirm-code succeeds.
Request body
The email address of the account being reset.
The new plain-text password. Hashed server-side before storage. Choose a strong password.
Response
Confirmation string, e.g.
"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
Bearer <access_token> — obtained from POST /auth/login.Request body
The email address of the account whose password is being changed.
The new password in plain text. Will be hashed server-side before storage.
Response
Confirmation string on success.
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
Bearer <access_token>.Response
Returns an array ofRole objects.
Unique role identifier.
Role name. Typical values:
"admin", "lider", "user".Optional human-readable description of the role’s permissions.
GET /auth
PROTECTED Returns all auth user account records. Used for administrative account management.Request headers
Bearer <access_token>.GET /auth/:id
PROTECTED Retrieves a single auth user account by its numeric ID.Path parameters
The numeric ID of the auth account to retrieve.
Request headers
Bearer <access_token>.PATCH /auth/:id
PROTECTED Partially updates an auth account. All body fields are optional; only the fields provided will be updated.Path parameters
The numeric ID of the auth account to update.
Request headers
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.
Display name for the account.
Updated email address. Must be unique across all accounts.
New password in plain text. Hashed server-side before storage.
Account active/inactive flag.
Updated given name(s) for the linked
Persona record.Updated paternal surname for the linked
Persona record.Updated maternal surname for the linked
Persona record.Updated date of birth (
YYYY-MM-DD) for the linked Persona record.Updated gender code (
"M" or "F") for the linked Persona record.ID of the role to assign to this account. See
GET /auth/roles/list for available values.DELETE /auth/:id
PROTECTED Soft-deletes an auth account by setting itsestado field to false. The record remains in the database for audit purposes.
Path parameters
The numeric ID of the auth account to deactivate.
Request headers
Bearer <access_token>.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 a401 response is received. Copy this into your frontend project (e.g. src/lib/api.ts).