URLs Base

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

API de Usuarios

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

Endpoints

1. 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)

Permisos Requeridos:

• action: READ
• resource: USER
• scope: PLATFORM

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..."

---

2. Obtener Detalle de Usuario

Obtiene la información detallada de un usuario específico. Permite enriquecer la respuesta con el contexto de una plataforma y entidad específica para obtener roles y atributos filtrados.

Endpoint: GET /users/:userId

Path Parameters:

• userId (requerido): ID del usuario (ObjectId válido)

Query Parameters:

• platform_id (opcional): ID de la plataforma para cargar contexto de roles y filtrado de atributos.
• entity_id (opcional): ID de la entidad para asociar los roles obtenidos.

Headers:

• Authorization: Bearer <token> (requerido)

Permisos Requeridos:

• action: READ
• resource: USER
• scope: ENTITY

Response (200 OK):

{
  "id": "string (ObjectId)",
  "userType": {
    "id": "string (ObjectId)",
    "name": "string"
  },
  "attributes": {
    "name": "string",
    "lastname": "string",
    "email": "string",
    "nickname": "string",
    "dni": "string"
  },
  "platform": {
    "id": "string (platformId)",
    "name": "string",
    "alias": "string",
    "description": "string",
    "roles": [
      {
        "id": "string (roleId)",
        "name": "string",
        "slug": "string",
        "context_type": "entity",
        "context_id": "string (entityId)"
      }
    ]
  },
  "entity": {
    "id": "string (entityId)",
    "brand_name": "string",
    "legal_name": "string",
    "domain": "string"
  },
  "createdAt": "string (ISO date)",
  "updatedAt": "string (ISO date)"
}

Response (404 Not Found):

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Usuario no encontrado"
}

Comportamiento:

• Si se envía platform_id, los atributos devueltos serán filtrados según la configuración de la plataforma para ese tipo de usuario.
• Si se envían platform_id y entity_id, se incluirán los roles que el usuario tiene asignados en esa plataforma, proyectados al contexto de la entidad.

Ejemplo de uso:

Obtener usuario básico:

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

Obtener usuario con contexto de plataforma y entidad:

curl -X GET "https://api.identia.cc/api/users/507f1f77bcf86cd799439011?platform_id=645d...&entity_id=61b0..." \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

---

3. Generar Enlace de Recuperación (Admin)

Permite a un administrador generar un token y una URL de recuperación de contraseña para un usuario específico, sin enviar un correo electrónico automáticamente.

Endpoint: POST /users/:userId/generate-recovery-link

Path Parameters:

• userId (requerido): ID del usuario (ObjectId válido)

Request Body:

{
  "base": "string (alias de la plataforma)"
}

Headers:

• Authorization: Bearer <token> (requerido - Admin)

Permisos Requeridos:

• action: UPDATE
• resource: USER
• scope: PLATFORM

Response (200 OK):

{
  "token": "string (JWT recovery token)",
  "url": "string (URL completa de recuperación)"
}

Response (403 Forbidden):

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "No tienes permisos para generar enlaces de recuperación"
}

Comportamiento:

• El sistema genera un token de recuperación único y lo asocia al usuario en la base de datos (invalidando cualquier token previo).
• La URL devuelta se construye usando la URL base de la plataforma y el token generado.
• Útil para procesos de soporte técnico donde el administrador desea entregar el link manualmente (vía chat u otros canales).

Ejemplo de uso:

curl -X POST https://api.identia.cc/api/users/507f1f77bcf86cd799439011/generate-recovery-link \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "base": "identia"
  }'

---

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

Notas de Seguridad

1. Los campos sensibles (password, tokens) son automáticamente excluidos
2. La búsqueda es insensible a mayúsculas/minúsculas para mejor usabilidad
3. 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

---

Última actualización: 05 de mayo de 2026