Gestión de usuarios y autenticación

Descripción del proceso de inicio de sesión

El proceso de inicio de sesión generalmente implica los siguientes pasos:

1. El usuario es registrado en el sistema por un administrador o mediante auto-registro.
2. El usuario es activado por el administrador cuando es necesario, solo después del auto-registro.
3. El usuario proporciona sus datos de acceso a través de la API del sistema, normalmente correo electrónico y contraseña.
4. El sistema valida las credenciales y, si son válidas, emite un JSON Web Token (JWT) de autenticación; los tokens se utilizan para acceso y refresco.
5. El usuario incluye el JSON Web Token como un token Bearer en el encabezado Authorization de las solicitudes API posteriores.
6. El sistema verifica el token en cada solicitud para asegurar que el usuario esté autenticado y autorizado para acceder a los recursos solicitados.
7. Si el token ha expirado o es inválido, el usuario debe autenticarse nuevamente para obtener un nuevo token.
8. Opcionalmente, se puede usar un mecanismo de refresh token para permitir que los usuarios obtengan un nuevo JWT sin volver a ingresar sus credenciales.
   • El refresh token se proporciona como token Bearer en el encabezado Authorization de un endpoint específico de refresco.
9. El usuario puede cerrar sesión, lo que normalmente implica invalidar el token actual en el servidor.
   • Invalidar el access token también invalida el refresh token vinculado a la sesión actual que gestiona el access token.

Endpoint que interactúa con el inicio de sesión

Inicia sesión un usuario con el correo electrónico y contraseña proporcionados.

POST /api/v1/users/login

{
  "email": "account.login@example.com",
  "password": "#P4ssword"
}

Respuesta esperada:

{
    "status": 200,
    "expiresIn": 3600,
    "type": "string",
    "message": "string",
    "tokenType": "bearer",
    "accessToken": "...",
    "refreshToken": "...",
    "data": [ ],
    "roles": [ { <Role> } ],
    "scopes": [ { <Scope> } ]
}

Descripción del mecanismo de refresh token

El mecanismo de refresh token está diseñado para permitir que los usuarios obtengan un nuevo access token sin volver a ingresar sus credenciales. Esto es especialmente útil para sesiones de larga duración donde el access token puede expirar.

¿Cómo se emiten, validan y renuevan los refresh tokens?

Emisión: Cuando un usuario inicia sesión correctamente, el sistema emite tanto un access token como un refresh token. El refresh token normalmente se almacena de forma segura en el lado del cliente (normalmente en el almacenamiento de sesión).

Validación: Cuando un cliente presenta un refresh token para obtener un nuevo access token, el sistema valida el refresh token comprobando su firma y fecha de expiración.

Renovación: Si el refresh token es válido, el sistema emite un nuevo access token (y posiblemente un nuevo refresh token) al cliente.

Endpoint para interactuar con refresh tokens

Refresca el access token usando el refresh token proporcionado.

POST /api/v1/users/refresh
Authorization: Bearer <refresh_token>

Respuesta esperada:

{
    "status": 200,
    "expiresIn": 3600,
    "type": "string",
    "message": "string",
    "tokenType": "bearer",
    "accessToken": "...",
    "refreshToken": "...",
    "data": [ ],
    "roles": [ { <Role> } ],
    "scopes": [ { <Scope> } ]
}

Descripción del proceso de cierre de sesión

Cerrar sesión normalmente implica invalidar el refresh token en el servidor, lo que también invalida el access token asociado y la sesión actual del emisor autenticado.

Proceso para cerrar sesión de los usuarios

1. El usuario inicia el proceso de cierre de sesión, normalmente haciendo clic en un botón “Cerrar sesión” en la interfaz.
2. La aplicación cliente envía una solicitud al servidor para cerrar la sesión del usuario.
3. El servidor invalida el refresh token y el access token asociados.
4. El servidor responde al cliente, confirmando el cierre de sesión.

Endpoints que interactúan con el cierre de sesión

Cierra la sesión del usuario actual invalidando los tokens de acceso y refresco actuales.

POST /api/v1/users/logout
Authorization: Bearer <access_token>
Expect: 200-ok

Descripción del proceso de cambio de contraseña

Proceso para cambiar contraseñas

1. La aplicación cliente envía una solicitud al servidor con la contraseña actual del usuario y la nueva contraseña.
2. El servidor valida la contraseña actual y, si es válida, actualiza la contraseña del usuario a la nueva.
3. El servidor responde al cliente, confirmando el cambio de contraseña.

Endpoint que interactúa con el cambio de contraseña

Actualiza la contraseña del usuario actual.

PUT /api/v1/users/change-password
Authorization: Bearer <access_token>

{
  "oldPassword": "#P4ssword",
  "newPassword": "#N3wP4ssword"
}

Respuesta esperada:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "pagination": { <Pagination> },
    "data": [
        {
            "id": 1,
            "username": "account.password",
            "updatedAt": "2025-02-20T-21:05:29.648Z"
        }
    ]
}

Descripción del proceso de registro de usuario

Estructuras de datos para usuarios

Estructura de Teléfono

La estructura de teléfono normalmente incluye campos como tipo de teléfono y número de teléfono.

Campo	Tipo	Descripción
phoneTypeId	string	El tipo de teléfono
phoneNumber	string	El número de teléfono

{
  "phoneTypeId": "2",
  "phoneNumber": "+1 (737) 888-1234"
}

Estructura de Dirección

La estructura de dirección normalmente incluye campos como calle, ciudad, estado, código postal y país.

Campo	Tipo	Descripción
street	string	La dirección (calle)
city	string	La ciudad
state	string	El estado o provincia
country	string	El país
postalcode	string	El código postal

{
  "street": "9442 N Capital of Texas Hwy",
  "city": "Austin",
  "state": "Texas",
  "country": "United States of America",
  "postalcode": "78759-0000"
}

Estructura de Usuario

La estructura de usuario normalmente incluye campos que pertenecen al perfil del usuario.

Campo	Tipo	Descripción
active	boolean	Indica si el usuario está activo
department	integer	El ID del departamento al que pertenece
doNotCall	boolean	Indica si el usuario no desea ser llamado
title	string	El título del usuario
salutation	string	La salutación del usuario
description	string	Una descripción del usuario
firstName	string	El nombre del usuario
lastName	string	El apellido del usuario
password	string	La contraseña del usuario
username	string	El nombre de usuario
email	string	El correo electrónico del usuario
phones	array	Un array de objetos teléfono
addresses	array	Un array de objetos dirección

{
  "active": true,
  "department": 1,
  "doNotCall": true,

  "title": "title",
  "salutation": "salutation",
  "description": "description",

  "email": "account.access@example.com",
  "username": "account.access",
  "password": "#P4ssword",
  "firstName": "Account",
  "lastName": "Access",

  "phones": [ { <Phone> } ],
  "addresses": [ { <Address> } ]
}

Endpoint para creación administrativa de usuario

Crea un nuevo usuario con los datos proporcionados por un usuario autenticado con permisos administrativos.

POST /api/v1/users/
Authorization: Bearer <access_token>

<User>

Endpoint para auto-registro de usuario

Crea un nuevo usuario con el nombre de usuario, correo electrónico y contraseña proporcionados.

POST /api/v1/users/register
Expect: 201-created

{
  "email": "account.register@example.com",
  "username": "account.register",
  "password": "#P4ssword",
  "firstName": "Account",
  "lastName": "Access"
}

Otras acciones relacionadas con la gestión de usuarios

Obtener todos los usuarios

Obtiene información sobre todos los usuarios. Debe obtener información sobre todos los usuarios activos.

Parámetros de consulta

Nombre	Tipo	Descripción	Requerido	Ejemplo
limit	number	Límite de registros	No	10
page	number	Página de registros	No	1
firstName	string	Nombre	No	John
lastName	string	Apellido	No	Doe
username	string	Nombre de usuario	No	username
email	string	Correo electrónico	No	account@example.com
active	boolean	Estado activo	No	true

GET /api/v1/users/
Expect: 200-ok

Respuesta esperada:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": [ { <User> } ],
    "pagination": { <Pagination> }
}

Obtener un usuario

Obtiene información sobre un usuario específico.

Parámetros de ruta

Nombre	Tipo	Descripción	Requerido	Ejemplo
id	string	ID de usuario	Sí	123

GET /api/v1/users/:id
Expect: 200-ok

Respuesta esperada:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": { <User> },
    "pagination": { <Pagination> }
}

Obtener el usuario actual

Obtiene información sobre el usuario actual.

GET /api/v1/users/me
GET /api/v1/users/profile
Authorization: Bearer <access_token>
Expect: 200-ok

Respuesta esperada:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": { <User> },
    "pagination": { <Pagination> }
}

Actualizar un usuario

Actualiza la información de un usuario específico.

Parámetros de ruta

Nombre	Tipo	Descripción	Requerido	Ejemplo
id	string	ID de usuario	Sí	123

PUT /api/v1/users/:id
Authorization: Bearer <access_token>
Expect: 200-ok

<User>

Respuesta esperada:

{
    "status": 200,
    "error": false,
    "errors": [ { } ],
    "message": "string",
    "data": { <User> },
    "pagination": { <Pagination> }
}