Users
User Routes

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. Obtener Perfil del Usuario Autenticado (Me)

Obtiene el perfil del usuario autenticado actual, extrayendo su identidad y contexto (plataforma y entidad) directamente del token JWT. La respuesta incluye atributos del usuario y los roles estrictamente asignados al contexto detectado.

Endpoint: GET /users/me

Headers:

Authorization: Bearer <token> (requerido)

Permisos Requeridos:

No requiere permisos específicos (roles) más allá de contar con un token válido.

Response (200 OK) - Con contexto de entidad (JWT contiene entityId):

{
  "id": "string (ObjectId)",
  "attributes": {
    "name": "string",
    "lastname": "string",
    "email": "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 (200 OK) - Sin contexto de entidad (JWT no contiene entityId):

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

Response (401 Unauthorized):

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Usuario no autenticado"
}

Response (403 Forbidden):

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "El usuario no tiene acceso a la entidad especificada dentro de esta plataforma"
}

Comportamiento:

Lee sub (userId), platformId y entityId del payload del token JWT.
Devuelve el perfil completo con los roles y configuraciones correspondientes a la plataforma y entidad del token JWT, aplicando las reglas de aislamiento de inquilinos (tenant isolation).
Si el usuario tiene un entityId en el token pero se le revocaron los roles en la base de datos para esa entidad, devuelve 403 Forbidden.
Si el token no tiene platformId ni entityId, devuelve el perfil base.

Importante

Los campos devueltos dentro del objeto attributes son dinámicos y son filtrados por el backend basándose en la configuración de la plataforma extraída del token JWT para el tipo de usuario correspondiente.

Ejemplo de uso:

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

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

3. 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) - Con query param entity_id:

{
  "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 (200 OK) - Sin query param entity_id:

{
  "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",
    "entities": [
      {
        "id": "string (entityId)",
        "brand_name": "string",
        "legal_name": "string",
        "domain": "string",
        "roles": [
          {
            "id": "string (roleId)",
            "name": "string",
            "slug": "string",
            "context_type": "entity",
            "context_id": "string (entityId)"
          }
        ]
      }
    ]
  },
  "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.

Importante

Los campos devueltos dentro del objeto attributes son dinámicos y se filtran según la configuración de la plataforma (platform_id) si se especifica; de lo contrario, se retornan todos los atributos base definidos para el tipo de usuario correspondiente.

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

4. Buscar Usuario por Credencial

Busca a un usuario utilizando una de sus credenciales (email, DNI, nickname). Retorna su perfil completo con los roles agrupados a nivel de plataforma y entidades, validando estrictamente su pertenencia al tenant.

Endpoint: GET /users/search/credential

Query Parameters:

typeCredential (requerido): Tipo de credencial a buscar (email, dni, nickname).
credential (requerido): Valor exacto de la credencial.
platform_id (opcional): ID de la plataforma para verificar pertenencia y enriquecer el perfil.
entity_id (opcional): ID de la entidad para filtrar los roles estrictamente a ese contexto.

Headers:

Authorization: Bearer <token> (requerido)

Permisos Requeridos:

action: READ
resource: USER
scope: PLATFORM

Response (200 OK) - Sin especificar entity_id:

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

Response (400 Bad Request):

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "La entidad no pertenece a la plataforma especificada"
}

Response (403 Forbidden):

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "El usuario no pertenece a la plataforma especificada" 
}

Response (404 Not Found):

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

Comportamiento:

Valida estrictamente que el usuario pertenezca a la plataforma si se envía platform_id.
Si se proporciona entity_id, asegura de forma estricta que el usuario cuente con roles vigentes dentro de esa entidad específica; caso contrario lanza un 403.
Si no se provee entity_id, agrupa ordenadamente las entidades donde participa el usuario junto con sus respectivos roles y separa los roles globales a nivel de plataforma.
Limpia los roles devolviendo únicamente id, name y slug.

Importante

Los campos devueltos dentro del objeto attributes son dinámicos y se filtran de acuerdo a la configuración de la plataforma (platform_id) obligatoria.

Ejemplo de uso:

Buscar por DNI dentro de una plataforma:

curl -X GET "https://api.identia.cc/api/users/search/credential?typeCredential=dni&credential=12345678&platform_id=645d..." \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

5. Actualizar Usuario

Endpoint: PATCH /users/:userId

Path Parameters:

userId (requerido): ID del usuario a actualizar (ObjectId válido).

Request Body:

{
  "attributes": {
    "name": "string (opcional)",
    "lastname": "string (opcional)",
    "email": "string (opcional)",
    "nickname": "string (opcional)",
    "password": "string (opcional, mínimo 8 caracteres)"
  },
  "platformId": "string (ObjectId, requerido si se envía entityId o roleId)",
  "entityId": "string (ObjectId, opcional)",
  "roleId": "string (ObjectId, opcional)",
  "expiresAt": "string (ISO Date, opcional, para expiración de rol)"
}

Importante

Los campos dentro del objeto attributes son dinámicos. La API evalúa y valida el contenido de attributes según la configuración de la plataforma (platformId) y el tipo de usuario (userType). Los atributos base listados arriba (name, lastname, etc.) corresponden a una Persona, pero pueden variar o incluir atributos personalizados según la plataforma.

Headers:

Authorization: Bearer <token> (requerido)

Permisos Requeridos:

Permitido a sí mismo (userId coincide con el sub del token) sin permisos adicionales.
Para actualizar a terceros, requiere:
- action: UPDATE
- resource: USER
- scope: PLATFORM

Response (200 OK):
Retorna el detalle del usuario actualizado con la estructura descrita en Obtener Detalle de Usuario.

Response (400 Bad Request):

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "La entidad no pertenece a la plataforma especificada"
}

Response (403 Forbidden):

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Acceso denegado. Permiso requerido: Actualizar usuario"
}

Comportamiento:

Si un usuario común se actualiza a sí mismo, solo puede actualizar sus atributos y el sistema los validará contra la configuración de su propia plataforma. No se le permite actualizar su DNI si su tipo de usuario es Persona.
Si un administrador realiza la actualización (con permisos UPDATE a nivel de PLATFORM), puede además especificar una combinación de platformId junto con entityId o roleId para asociar al usuario a una nueva entidad y asignarle un rol en esa entidad dentro de la plataforma.
Si el administrador solo envía platformId y attributes, la API únicamente validará y actualizará los atributos bajo el esquema de esa plataforma, sin modificar ni crear asignaciones de entidad o roles.
Valida de forma estricta que la entidad pertenezca a la plataforma especificada.
Valida de forma estricta que el rol pertenezca a la plataforma especificada.
Si el usuario ya pertenece a la entidad, la operación no falla (es idempotente en su relación).

Ejemplo de uso:

curl -X PATCH https://api.identia.cc/api/users/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "name": "Brayan",
      "lastname": "Salazar"
    },
    "platformId": "678536a510cea9ecbc7053da",
    "entityId": "623222f3790e4900124c337e",
    "roleId": "69af5c2138a969514d74c28f"
  }'

6. Generar Enlace de Recuperación (Admin)

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

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

Última actualización: 19 de mayo de 2026

URLs Base

API de Usuarios

Endpoints

1. Obtener Perfil del Usuario Autenticado (Me)

2. Listar Usuarios

3. Obtener Detalle de Usuario

4. Buscar Usuario por Credencial

5. Actualizar Usuario

6. Generar Enlace de Recuperación (Admin)

Códigos de Estado HTTP

Notas de Seguridad

Casos de Uso Comunes

Gestión de Usuarios

Auditoría y Monitoreo

Integraciones de Terceros

On This Page