URLs Base

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

API de Plataformas

Todos los endpoints regulares requieren autenticación JWT via header Authorization: Bearer <token> y están bajo el prefijo /platforms, a excepción de los endpoints públicos como la obtención de la clave pública.

Obtener Clave Pública de Plataforma

Obtiene la clave pública RSA asociada a una plataforma específica para validación offline de JWTs. Este endpoint es público y no requiere autenticación.

Endpoint: GET /platforms/:alias/pub

Path Parameters:

  • alias (requerido): Alias de la plataforma (string)

Headers:

  • Ninguno (Endpoint público)

Response (200 OK):

{
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----"
}

Response (404 Not Found):

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Plataforma no encontrada"
}

Ejemplo con curl:

curl -X GET https://api.identia.cc/api/platforms/mi-plataforma/pub

Obtener Usuarios de Plataforma

Obtiene los usuarios asociados a una plataforma específica, opcionalmente filtrados por rol.

Endpoint: GET /platforms/:platformId/users

Path Parameters:

  • platformId (requerido): ID de la plataforma (ObjectId)

Query Parameters:

  • roleId (opcional): ID del rol para filtrar usuarios (ObjectId)

Headers:

  • Authorization: Bearer <token> (requerido)

Response (200 OK) - Sin filtro de rol:

{
  "success": true,
  "data": [
    {
      "userId": "507f1f77bcf86cd799439011",
      "name": "Juan Pérez",
      "email": "juan.perez@example.com",
      "roles": [
        {
          "roleId": "507f1f77bcf86cd799439012",
          "roleName": "Administrador",
          "permissions": ["read", "write", "delete"],
          "scope": "platform"
        }
      ]
    }
  ],
  "message": "Usuarios obtenidos exitosamente"
}

Response (200 OK) - Con filtro de rol:

{
  "success": true,
  "data": [
    {
      "userId": "507f1f77bcf86cd799439011",
      "name": "Juan Pérez",
      "email": "juan.perez@example.com",
      "roleId": "507f1f77bcf86cd799439012",
      "roleName": "Administrador"
    }
  ],
  "message": "Usuarios obtenidos exitosamente"
}

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 acceder a los usuarios de esta plataforma"
}

Response (404 Not Found):

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Plataforma no encontrada"
}

Comportamiento:

  • Si se proporciona roleId: Devuelve usuarios que tienen asignado ese rol específico en la plataforma (estructura simplificada)
  • Si no se proporciona roleId: Devuelve todos los usuarios con sus roles en la plataforma (estructura con array de roles)

Ejemplo con curl (todos los usuarios de la plataforma):

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

Ejemplo con curl (usuarios filtrados por rol):

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

Ejemplo de respuesta (sin filtro de rol):

{
  "success": true,
  "data": [
    {
      "userId": "507f1f77bcf86cd799439015",
      "name": "Juan Pérez",
      "email": "juan.perez@example.com",
      "roles": [
        {
          "roleId": "507f1f77bcf86cd799439014",
          "roleName": "Administrador",
          "permissions": ["read", "write", "delete"],
          "scope": "platform"
        }
      ]
    },
    {
      "userId": "507f1f77bcf86cd799439016",
      "name": "María González",
      "email": "maria.gonzalez@example.com",
      "roles": [
        {
          "roleId": "507f1f77bcf86cd799439017",
          "roleName": "Usuario",
          "permissions": ["read"],
          "scope": "platform"
        }
      ]
    }
  ],
  "message": "Usuarios obtenidos exitosamente"
}

Obtener Usuarios por Entidad en Plataforma

Obtiene la lista de usuarios asociados a una entidad específica dentro de una plataforma, con soporte para paginación, búsqueda y ordenamiento.

Endpoint: GET /platforms/:platformId/entities/:entityId/users

Path Parameters:

  • platformId (requerido): ID de la plataforma (ObjectId)
  • entityId (requerido): ID de la entidad (ObjectId)

Query Parameters:

  • page (opcional): Número de página, mínimo 1 (default: 1)
  • limit (opcional): Cantidad de resultados por página, 1-100 (default: 20)
  • search (opcional): Término de búsqueda para nombre, apellido, email o nickname (string)
  • sortBy (opcional): Campo por el cual ordenar: name, lastname, email, nickname (default: name)
  • order (opcional): Dirección del ordenamiento: asc, desc (default: asc)

Headers:

  • Authorization: Bearer <token> (requerido)

Response (200 OK):

{
  "users": [
    {
      "id": "507f1f77bcf86cd799439011",
      "userType": {
        "id": "507f1f77bcf86cd799439012",
        "name": "Persona"
      },
      "attributes": {
        "name": "Juan",
        "lastname": "Pérez",
        "email": "juan.perez@example.com",
        "nickname": "jperez"
      },
      "created_at": "2024-03-18T10:00:00.000Z",
      "updated_at": "2024-03-18T11:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Ejemplo con curl:

curl -X GET "https://api.identia.cc/api/platforms/507f1f77bcf86cd799439011/entities/507f1f77bcf86cd799439015/users?page=1&limit=10&search=juan&sortBy=lastname&order=asc" \
  -H "Authorization: Bearer <token>"

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
  • 404 Not Found: Plataforma no encontrada
  • 500 Internal Server Error: Error del servidor

Permisos Requeridos

Este endpoint requiere uno de los siguientes permisos:

  • read:user con scope system
  • read:user con scope platform
  • manage:user con scope system

Notas de Seguridad

  1. Solo se devuelven usuarios que tienen al menos un rol asignado en la plataforma
  2. Los datos sensibles de los usuarios están protegidos por permisos
  3. El filtrado por rol permite acceder a subconjuntos específicos de usuarios
  4. Se recomienda usar HTTPS en producción

Casos de Uso Comunes

Gestión de Usuarios por Plataforma

  • Obtener lista completa de usuarios activos en una plataforma
  • Filtrar usuarios por roles específicos para gestión de permisos
  • Auditoría de accesos y roles en plataformas

Administración de Roles

  • Ver qué usuarios tienen un rol específico asignado
  • Gestionar permisos a nivel de plataforma
  • Monitoreo de accesos por rol
Previous User Routes