Cuando un sistema de negocio remoto se conecta a la plataforma, lo difícil no suele ser la llamada a la API. Lo difícil es decidir quién guarda cada credencial, cuánto dura y con qué rapidez surte efecto una membresía revocada. Estas tres preguntas determinan si el sistema seguirá comportándose bien meses después. Esto es lo que sostenemos en ese camino y dónde están los límites.
Dos niveles de credencial, y la de larga duración no sale del servidor
La plataforma emite dos tipos de identidad. La identidad de servicio de módulo es de larga duración, vive solo en el servidor del sistema de negocio y sirve para intercambiar un Launch Grant (POST /integration/v1/sso/launch-grants/exchange) y para solicitar un token de servicio de instancia (POST /integration/v1/service-tokens). El token de servicio de instancia es de corta duración: cinco minutos como máximo, audiencia fija y ámbitos acotados a la petición concreta, devuelto con no-store.
Por tanto, el navegador nunca recibe credenciales de módulo. El frontend solo entrega el código de lanzamiento que ha recibido a su propio backend, y todo intercambio ocurre en el servidor. Para los tokens de corta duración, el SDK cachea por instancia y conjunto de ámbitos solicitado durante 300 segundos como máximo, sin Refresh: pide uno nuevo cuando la vida restante cae por debajo de una ventana de seguridad, una ráfaga simultánea provoca un único intercambio y los tokens nunca se reutilizan entre instancias.
El Launch es un intercambio de un solo uso que termina en su propia sesión
Quien llega desde la plataforma trae un código de lanzamiento, no una credencial de larga duración. El backend intercambia y consume el Grant con la identidad de servicio de módulo y después establece la sesión local del sistema de negocio. Esa sesión solo contiene identidad derivada: ni token de plataforma, ni código de lanzamiento, ni Client Secret, ni claims completos.
Tanto el intercambio como las comprobaciones posteriores de sesión verifican firmas: el JWKS de ejecución de la plataforma comprueba algoritmo, emisor, audiencia, vigencia, token_use, cuenta e instancia de aplicación, y ámbitos, con un origen de claves que rechaza redirecciones y limita el tamaño de la respuesta. Hay un punto que se confunde con facilidad: que la página de acceso diga «conectado» solo prueba que el backend puede leer las claves públicas. No prueba que el visitante haya iniciado sesión ni que el camino de Launch funcione. Mantenga esas tres afirmaciones separadas.
Cuando se revoca una membresía, la sesión local debe converger
Una sesión válida en la plataforma no significa que la sesión local pueda durar indefinidamente. Durante una sesión larga, un miembro eliminado, un rol cambiado o una instancia suspendida deben llegar al sistema de negocio en una ventana acotada. El mecanismo es una comprobación por lotes con la identidad de servicio de instancia (POST /integration/v1/session-checks): active es verdadero solo si la instancia, la membresía de instancia, la cuenta y la membresía de cuenta son válidas a la vez, mientras que quienes no son miembros y los usuarios desconocidos devuelven active=false, de modo que no se filtra la existencia de la membresía. Cada sistema converge en la ventana que declara y, en la práctica, la ventana de escritura puede ser más corta que la de lectura.
Si los ámbitos no alcanzan, se falla en local
Toda petición de ejecución lleva ámbitos. El SDK solo devuelve credenciales utilizables cuando los ámbitos realmente concedidos cubren esa petición; en caso contrario falla en local y no envía ninguna petición de negocio. El valor de esta regla es separar «la plataforma no autorizó esto» de «la llamada a la plataforma falló»: lo primero es un problema de configuración que debe verse de inmediato, en lugar de convertirse en un error opaco del proveedor.
La idempotencia y los reintentos son responsabilidad de quien llama
El SDK nunca reintenta una petición por su cuenta. Las operaciones de escritura deben llevar una clave de idempotencia estable que aporte quien llama, y una petición fallida no se reenvía, porque «resultado desconocido» y «fallo» son estados distintos, y solo el sistema de negocio sabe si conviene reenviar, consultar o avisar al usuario. En cuanto a errores, los Problem Details de la plataforma se asignan a clases estables (no autenticado, prohibido, conflicto, límite de tasa, error de servidor, etc.) con una marca de reintentabilidad, y las credenciales y los cuerpos de respuesta nunca llegan a los registros ni a la serialización de errores.
Dos artefactos, dos vías de obtención
Los dos SDK no son igual de accesibles, así que confirme primero cuál le corresponde. En TypeScript y Node el paquete es @td-runlume/platform-integration-sdk en npm público, Apache-2.0, para uso en el servidor. En Java la coordenada es app.runlume.platform:platform-integration-sdk-java, servida desde el repositorio Nexus de la plataforma y no disponible en Maven Central; solo puede usarse con las credenciales y la licencia que conceda la plataforma, y los artefactos no deben redistribuirse. Las integraciones Java suelen combinarlo con el starter de Spring Boot, que ensambla los componentes del SDK y la cadena de validez de la sesión local, y deja al sistema de negocio dos puntos de extensión: el límite de sesión y la lectura del espacio de trabajo.
Las rutas de los endpoints, los nombres de ámbito y las capacidades disponibles siguen el contrato y la documentación acordados en el alta. Este artículo solo cubre los límites que debe sostener el servidor; las capacidades en sí empiezan en capacidades de la plataforma.