Users
User Routes

URLs Base

URL Principal: https://api.identia.cc/api
URL Secundario: https://identiapreview.multibacks.multipacha.com/api

API de Usuarios - Listar Usuarios

Todos los endpoints requieren autenticación JWT via header Authorization: Bearer <token> y están bajo el prefijo /users.

Listar Usuarios

Obtiene una lista paginada de usuarios con opciones de filtrado por búsqueda y entidad.

Endpoint: GET /users

Query Parameters:

page (opcional): Número de página (integer, mínimo 1, default: 1)
limit (opcional): Número de usuarios por página (integer, mínimo 1, máximo 100, default: 20)
search (opcional): Término de búsqueda (string, máximo 200 caracteres). Busca en nombre, email y nickname
entityId (opcional): ID de entidad para filtrar usuarios (ObjectId válido)

Headers:

Authorization: Bearer <token> (requerido)

Response (200 OK):

{
  "users": [
    {
      "id": "string (ObjectId)",
      "userType": {
        "id": "string (ObjectId)",
        "name": "string"
      },
      "attributes": {
        "name": "string",
        "lastname": "string",
        "email": "string",
        "nickname": "string",
        "dni": "string"
      },
      "adminId": "string (ObjectId)",
      "entityId": "string (ObjectId)",
      "createdAt": "string (ISO date)",
      "updatedAt": "string (ISO date)"
    }
  ],
  "pagination": {
    "page": "number",
    "limit": "number",
    "total": "number",
    "pages": "number"
  }
}

Response (401 Unauthorized):

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Token inválido o faltante"
}

Response (403 Forbidden):

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "No tienes permisos para listar usuarios"
}

Comportamiento:

La búsqueda (search) se realiza en los campos name, email y nickname de forma insensible a mayúsculas/minúsculas
Si se proporciona entityId, solo se devuelven usuarios que pertenecen a esa entidad
Los usuarios se devuelven en el orden que determine la base de datos (sin ordenamiento específico)
Los campos sensibles como password, recovery_password_token, link_token son excluidos de la respuesta
La paginación incluye información completa sobre el total de resultados y páginas disponibles

Ejemplos de uso:

Listar todos los usuarios (página 1, 20 por página):

curl -X GET https://api.identia.cc/api/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Buscar usuarios por término:

curl -X GET "https://api.identia.cc/api/users?search=Juan" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Listar usuarios de una entidad específica:

curl -X GET "https://api.identia.cc/api/users?entityId=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Paginación personalizada:

curl -X GET "https://api.identia.cc/api/users?page=2&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Combinar filtros:

curl -X GET "https://api.identia.cc/api/users?page=1&limit=5&search=admin&entityId=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Códigos de Estado HTTP

200 OK: Operación exitosa
401 Unauthorized: Token de autenticación inválido o faltante
403 Forbidden: Permisos insuficientes para acceder al recurso

Permisos Requeridos

Este endpoint requiere uno de los siguientes permisos:

read:user con scope system
read:user con scope platform

Notas de Seguridad

Solo usuarios con permisos de sistema pueden listar usuarios
Los campos sensibles (password, tokens) son automáticamente excluidos
La búsqueda es insensible a mayúsculas/minúsculas para mejor usabilidad
El filtrado por entidad permite segmentar resultados según el contexto

Casos de Uso Comunes

Gestión de Usuarios

Obtener lista completa de usuarios para administración
Buscar usuarios específicos por nombre, email o nickname
Gestionar usuarios dentro de una entidad específica
Implementar interfaces de administración con paginación

Auditoría y Monitoreo

Ver usuarios activos en el sistema
Filtrar usuarios por entidad para análisis de acceso
Monitoreo de crecimiento de usuarios por página

Integraciones de Terceros

Sincronización de usuarios con sistemas externos
Exportación de datos de usuarios con filtros específicos