API de autenticación: login, refresh, logout y contraseña

Todos los endpoints de autenticación se encuentran bajo el prefijo /api/auth. La mayoría son públicos y no requieren token. Las excepciones son GET /api/auth/me y POST /api/auth/logout, que requieren un Authorization: Bearer <accessToken> válido en el encabezado de la solicitud.

Formato de respuesta estándar

Todos los endpoints devuelven una envoltura JSON consistente:

{
  "success": true,
  "message": "Descripción de la operación",
  "data": { ... }
}

En caso de error:

{
  "success": false,
  "message": "Descripción del error",
  "errors": [ ... ]
}

Autenticación requerida: No Autentica a un usuario con su correo electrónico y contraseña. Si las credenciales son válidas y la cuenta está activa, devuelve un accessToken de corta duración (para adjuntar en cada solicitud subsiguiente) y un refreshToken de larga duración (para renovar el access token).

Request body

string

required

Correo electrónico del usuario. Debe ser un email válido. Se normaliza automáticamente a minúsculas.

password

string

required

Contraseña del usuario. No puede estar vacía.

Response

success

boolean

true si la operación fue exitosa.

message

string

"Inicio de sesión exitoso"

data

object

Show data

accessToken

string

JWT de corta duración para autenticar solicitudes a la API. Incluirlo en el header Authorization: Bearer <accessToken>.

refreshToken

string

JWT de larga duración para renovar el accessToken cuando expire.

user

object

Show user

integer

ID único del usuario.

nombre

string

Nombre del usuario.

string

Correo electrónico del usuario.

role

string

Rol del usuario en el sistema (p. ej. ADMIN, USER).

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@biblioteca.com",
    "password": "miContraseña123"
  }'

{
  "success": true,
  "message": "Inicio de sesión exitoso",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "nombre": "Administrador",
      "email": "admin@biblioteca.com",
      "role": "ADMIN"
    }
  }
}

Errores

Código	Motivo
`400`	Body inválido o campos faltantes.
`401`	Credenciales incorrectas (email o contraseña inválidos).
`403`	La cuenta está desactivada. Contactar al administrador.
`422`	Error de validación: el email no tiene formato válido o la contraseña está vacía.

POST /api/auth/refresh

Autenticación requerida: No Renueva el accessToken utilizando un refreshToken válido. El usuario asociado al token debe existir y tener la cuenta activa para que la renovación sea exitosa.

Request body

refreshToken

string

required

El refresh token previamente obtenido en el endpoint de login. Si se omite, se devuelve un error 400 inmediatamente.

Response

success

boolean

true si la operación fue exitosa.

message

string

"Token renovado"

data

object

Show data

accessToken

string

Nuevo JWT de acceso de corta duración.

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

{
  "success": true,
  "message": "Token renovado",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Errores

Código	Motivo
`400`	`refreshToken` ausente en el body.
`401`	El refresh token es inválido, está expirado, o el usuario asociado fue desactivado.

GET /api/auth/me

Autenticación requerida: Sí — Authorization: Bearer <accessToken> Devuelve el perfil del usuario autenticado actualmente. El ID del usuario se extrae directamente del JWT decodificado por el middleware de autenticación. La contraseña nunca se incluye en la respuesta.

Response

success

boolean

true si la operación fue exitosa.

message

string

"Operación exitosa"

data

object

Show data

integer

ID único del usuario.

nombre

string

Nombre del usuario.

string

Correo electrónico del usuario.

role

string

Rol del usuario (p. ej. ADMIN, USER).

createdAt

string (ISO 8601)

Fecha y hora de creación de la cuenta.

Ejemplo

curl -X GET https://api.bibliotecalapalabra.com/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "id": 1,
    "nombre": "Administrador",
    "email": "admin@biblioteca.com",
    "role": "ADMIN",
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.

POST /api/auth/logout

Autenticación requerida: Sí — Authorization: Bearer <accessToken> Cierra la sesión del usuario autenticado. No requiere body. El cliente debe descartar los tokens almacenados localmente tras recibir la respuesta exitosa.

Request body

No se requiere body.

Response

success

boolean

true si la operación fue exitosa.

message

string

"Sesión cerrada correctamente"

data

null

Siempre null.

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Sesión cerrada correctamente",
  "data": null
}

Errores

Código	Motivo
`401`	Token ausente, inválido o expirado.

POST /api/auth/forgot-password

Autenticación requerida: No Inicia el flujo de recuperación de contraseña. Si el correo electrónico existe en el sistema, se envía un enlace de restablecimiento al email registrado. La respuesta nunca revela si el email existe o no para proteger la privacidad de los usuarios.

El enlace de recuperación tiene una validez de 1 hora a partir del momento en que se genera. El envío del correo se realiza a través del servidor SMTP configurado en las variables de entorno del backend.

Request body

string

required

Correo electrónico asociado a la cuenta. Debe ser un email válido. Se normaliza automáticamente.

Response

success

boolean

true siempre (independientemente de si el email existe).

message

string

"Si el correo existe en el sistema, recibirás un enlace de recuperación"

data

null

Siempre null.

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@ejemplo.com"
  }'

{
  "success": true,
  "message": "Si el correo existe en el sistema, recibirás un enlace de recuperación",
  "data": null
}

Errores

Código	Motivo
`422`	El email no tiene formato válido.

POST /api/auth/reset-password

Autenticación requerida: No Restablece la contraseña de un usuario usando el token de recuperación recibido por email. El token es de un solo uso y expira 1 hora después de su generación. Internamente, el token recibido se hashea con SHA-256 antes de compararse con el registro en la base de datos.

Request body

token

string

required

Token de recuperación recibido en el enlace enviado por email. No puede estar vacío.

password

string

required

Nueva contraseña para la cuenta. Debe tener al menos 6 caracteres.

Response

success

boolean

true si la contraseña fue actualizada correctamente.

message

string

"Contraseña actualizada correctamente"

data

null

Siempre null.

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a3f9e2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1",
    "password": "nuevaContraseña456"
  }'

{
  "success": true,
  "message": "Contraseña actualizada correctamente",
  "data": null
}

Errores

Código	Motivo
`400`	El token es inválido, ya fue usado, o ha expirado (más de 1 hora).
`422`	La nueva contraseña tiene menos de 6 caracteres, o el token está ausente.

POST /api/auth/register-request

Autenticación requerida: No Envía una solicitud de registro al administrador de la biblioteca. Este endpoint no crea una cuenta de usuario. Su único efecto es disparar un correo electrónico de notificación al administrador con los datos del solicitante. El administrador deberá crear la cuenta manualmente.

Este endpoint es ideal para bibliotecas que requieren aprobación manual antes de permitir el acceso al sistema. El envío del correo depende de la configuración SMTP del entorno.

Request body

nombre

string

required

Nombre del solicitante. Se aplica trim automático. No puede estar vacío.

string

required

Correo electrónico de contacto del solicitante. Debe ser un email válido. Se normaliza automáticamente.

telefono

string

Número de teléfono opcional del solicitante. Se aplica trim automático.

mensaje

string

Mensaje opcional del solicitante (p. ej. motivo de la solicitud). Se aplica trim automático.

Response

success

boolean

true si la solicitud fue procesada.

message

string

"Tu solicitud ha sido enviada. El administrador se comunicará contigo."

data

null

Siempre null.

Ejemplo

curl -X POST https://api.bibliotecalapalabra.com/api/auth/register-request \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María González",
    "email": "maria@ejemplo.com",
    "telefono": "+54 9 11 1234-5678",
    "mensaje": "Me gustaría acceder al sistema para gestionar los préstamos."
  }'

{
  "success": true,
  "message": "Tu solicitud ha sido enviada. El administrador se comunicará contigo.",
  "data": null
}

Errores

Código	Motivo
`422`	El nombre está vacío o el email no tiene formato válido.

Autenticación

Recursos

API de autenticación: login, refresh, logout y contraseña

Formato de respuesta estándar

Request body

Response

Ejemplo

Errores

POST /api/auth/refresh

Request body

Response

Ejemplo

Errores

GET /api/auth/me

Response

Ejemplo

Errores

POST /api/auth/logout

Request body

Response

Ejemplo

Errores

POST /api/auth/forgot-password

Request body

Response

Ejemplo

Errores

POST /api/auth/reset-password

Request body

Response

Ejemplo

Errores

POST /api/auth/register-request

Request body

Response

Ejemplo

Errores

Build docs developers (and LLMs) love

Autenticación

Recursos

Documentation Index

​Formato de respuesta estándar

​POST /api/auth/login

​Request body

​Response

​Ejemplo

​Errores

​POST /api/auth/refresh

​Request body

​Response

​Ejemplo

​Errores

​GET /api/auth/me

​Response

​Ejemplo

​Errores

​POST /api/auth/logout

​Request body

​Response

​Ejemplo

​Errores

​POST /api/auth/forgot-password

​Request body

​Response

​Ejemplo

​Errores

​POST /api/auth/reset-password

​Request body

​Response

​Ejemplo

​Errores

​POST /api/auth/register-request

​Request body

​Response

​Ejemplo

​Errores

Build docs developers (and LLMs) love

Formato de respuesta estándar

POST /api/auth/login

Request body

Response

Ejemplo

Errores

POST /api/auth/refresh

Request body

Response

Ejemplo

Errores

GET /api/auth/me

Response

Ejemplo

Errores

POST /api/auth/logout

Request body

Response

Ejemplo

Errores

POST /api/auth/forgot-password

Request body

Response

Ejemplo

Errores

POST /api/auth/reset-password

Request body

Response

Ejemplo

Errores

POST /api/auth/register-request

Request body

Response

Ejemplo

Errores