Authentication API — Login and Password Management - UZDI

UZDI uses token-based authentication. After a successful login the frontend stores the bearer token in localStorage under the key uzdi_token and the serialised user object under uzdi_user. Every subsequent HTTP request automatically attaches the token via an Axios request interceptor.

All endpoints share the global prefix /api/v1. The examples in this page use that full path.

How the token is used

The Vue 3 frontend configures a single shared Axios instance (src/services/api.ts). A request interceptor reads uzdi_token from localStorage and injects it as an Authorization header on every outgoing request:

src/services/api.ts

import axios from 'axios'

const api = axios.create({
  baseURL: `${import.meta.env.VITE_API_BASE_URL}/api/v1`,
  headers: { 'Content-Type': 'application/json' },
})

// ── Request interceptor — attach Bearer token ──────────────────────────────
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('uzdi_token')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

// ── Response interceptor — handle 401 globally ────────────────────────────
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('uzdi_token')
      localStorage.removeItem('uzdi_user')
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

export default api

Authenticates a user by comparing the supplied plain-text password against the bcrypt hash stored in seguridad.prsn. The service queries both the prsnlogn and prsnmail columns, so the login field accepts either a login handle or a registered email address. On success the service strips the password field from the returned user object before sending the response. Authentication required: None

Request body

The user’s login handle or registered email address. The service queries both the prsnlogn and prsnmail columns, so either value is accepted.

password

string

required

Plain-text password. The service verifies it with bcrypt.compare() against the stored hash — the raw value is never persisted.

Success response — `200 OK`

message

string

Human-readable confirmation. Always 'Login exitoso' on success.

token

string

Bearer token to include in subsequent requests as Authorization: Bearer {token}.

user

object

The authenticated user record. The password field is deleted before the object is returned — all other entity columns are included.

Show user object fields

number

Internal primary key (prsn_id).

uzdi_id

number | null

Foreign key to the UZDI unit the user belongs to.

tppr_id

number | null

Profile / role identifier (1 = Técnico, 2 = Coordinador, 3 = Administrador).

nombres

string

First name(s) (prsnnmbr, max 31 chars).

apellidos

string

Last name(s) (prsnapll, max 31 chars).

sexo

string | null

Single character: 'M', 'F', or 'O'.

direccion

string | null

Street address (max 255 chars).

telefono

string | null

Phone number (max 63 chars).

correo

string | null

Email address (max 63 chars).

Unique login handle (prsnlogn, max 30 chars).

observaciones

string | null

Free-text notes (max 255 chars).

Error responses

Status	Body	Cause
`401 Unauthorized`	`{ "message": "Credenciales inválidas", "statusCode": 401 }`	User not found or bcrypt comparison failed. The service returns the same message for both cases to avoid user enumeration.
`400 Bad Request`	Validation error array	`login` or `password` field is missing or empty (enforced by `ValidationPipe`).

Examples

curl -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "login": "jdoe",
    "password": "mySecret123"
  }'

Example response:

{
  "message": "Login exitoso",
  "token": "mock-jwt-token-generado-por-la-app",
  "user": {
    "id": 42,
    "uzdi_id": 3,
    "tppr_id": 2,
    "nombres": "Juan",
    "apellidos": "Doe",
    "sexo": "M",
    "direccion": "Av. 12 de Octubre",
    "telefono": "0991234567",
    "correo": "[email protected]",
    "login": "jdoe",
    "observaciones": null
  }
}

POST /api/v1/auth/change-password

Updates the password of an existing user. The service re-validates the current password with bcrypt before hashing and persisting the new one. Authentication required: Bearer token (Authorization: Bearer {token})

Request body

userId

number

required

Numeric ID of the user whose password is being changed (matches prsn_id / User.id).

currentPassword

string

required

The user’s current plain-text password. Verified against the stored bcrypt hash before any update is applied.

newPassword

string

required

The desired new password in plain text. Must be at least 8 characters (enforced by the frontend; the backend hashes whatever is sent with a cost factor of 10).

Success response — `200 OK`

message

string

Always 'Contraseña actualizada correctamente' on success.

Error responses

Status	Body	Cause
`401 Unauthorized`	`{ "message": "Usuario no encontrado", "statusCode": 401 }`	No user exists with the given `userId`.
`401 Unauthorized`	`{ "message": "Contraseña actual incorrecta", "statusCode": 401 }`	`currentPassword` did not match the stored bcrypt hash.

If the current password check fails the endpoint returns 401 Unauthorized. No partial update is ever applied — the password remains unchanged.

Example

curl -X POST https://api.example.com/api/v1/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "userId": 42,
    "currentPassword": "mySecret123",
    "newPassword": "newSecure456"
  }'

Example response:

{
  "message": "Contraseña actualizada correctamente"
}

Token storage and session lifecycle

`localStorage` key	Value	Set when
`uzdi_token`	Bearer token string	Successful login
`uzdi_user`	JSON-serialised user object	Successful login

Both keys are cleared automatically by the Axios response interceptor whenever any API call returns 401 Unauthorized. After clearing, the user is redirected to /login:

api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('uzdi_token')
      localStorage.removeItem('uzdi_user')
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

Explicit logout (clicking the sidebar logout button) also navigates to /login. If you need to programmatically end a session, remove both localStorage keys before redirecting.

Authentication

Core Resources

Catalogs & Settings

Authentication API — Login and Password Management

How the token is used

Request body

Success response — `200 OK`

Error responses

Examples

POST /api/v1/auth/change-password

Request body

Success response — `200 OK`

Error responses

Example

Token storage and session lifecycle

Build docs developers (and LLMs) love

Authentication

Core Resources

Catalogs & Settings

Documentation Index

​How the token is used

​POST /api/v1/auth/login

​Request body

​Success response — 200 OK

​Error responses

​Examples

​POST /api/v1/auth/change-password

​Request body

​Success response — 200 OK

​Error responses

​Example

​Token storage and session lifecycle

Build docs developers (and LLMs) love

How the token is used

POST /api/v1/auth/login

Request body

Success response — `200 OK`

Error responses

Examples

POST /api/v1/auth/change-password

Request body

Success response — `200 OK`

Error responses

Example

Token storage and session lifecycle