Lorsqu’un système métier distant se connecte à la plateforme, la difficulté vient rarement de l’appel d’API lui-même. Elle vient du choix de qui détient quel identifiant, combien de temps il reste valable et en combien de temps une adhésion révoquée produit son effet. Ces trois questions déterminent si le système se comporte encore correctement des mois plus tard. Voici ce que nous tenons sur ce chemin, et où se situent les limites.

Deux niveaux d’identifiants, le durable ne quitte pas le serveur

La plateforme émet deux types d’identité. L’identité de service de module est durable, elle reste uniquement sur le serveur du système métier, et sert à échanger un Launch Grant (POST /integration/v1/sso/launch-grants/exchange) et à demander un jeton de service d’instance (POST /integration/v1/service-tokens). Le jeton de service d’instance est de courte durée : cinq minutes au maximum, audience fixe et périmètres restreints à la requête en cours, renvoyé avec no-store.

Le navigateur ne reçoit donc jamais d’identifiants de module. Le frontend transmet simplement le code de lancement reçu à son propre backend, et tous les échanges ont lieu côté serveur. Pour les jetons de courte durée, le SDK met en cache par instance et par ensemble de périmètres demandé, pendant 300 secondes au maximum, sans Refresh : il en demande un nouveau lorsque la durée restante passe sous une fenêtre de sécurité, un appel simultané ne déclenche qu’un seul échange, et un jeton n’est jamais réutilisé d’une instance à l’autre.

Le Launch est un échange à usage unique, qui aboutit à votre propre session

Un visiteur venant de la plateforme apporte un code de lancement, pas un identifiant durable. Le backend échange et consomme le Grant avec l’identité de service de module, puis établit la session locale du système métier. Cette session ne contient que de l’identité dérivée : ni jeton de plateforme, ni code de lancement, ni Client Secret, ni revendications complètes.

L’échange comme les vérifications de session ultérieures contrôlent les signatures : le JWKS d’exécution de la plateforme vérifie l’algorithme, l’émetteur, l’audience, la période de validité, token_use, le compte et l’instance d’application, ainsi que les périmètres, avec une source de clés qui refuse les redirections et plafonne la taille des réponses. Un point prête facilement à confusion : « connexion établie » sur la page de connexion prouve seulement que le backend peut lire les clés publiques. Cela ne prouve ni que le visiteur est authentifié, ni que le chemin de Launch fonctionne. Gardez ces trois affirmations séparées.

Quand une adhésion est révoquée, la session locale doit converger

Une session valide sur la plateforme ne signifie pas qu’une session locale peut durer indéfiniment. Au fil d’une session longue, un membre retiré, un rôle modifié ou une instance suspendue doivent atteindre le système métier dans une fenêtre bornée. Le mécanisme est une vérification par lots sous l’identité de service d’instance (POST /integration/v1/session-checks) : active n’est vrai que si l’instance, l’adhésion d’instance, le compte et l’adhésion de compte sont tous valides, tandis que les non-membres et les utilisateurs inconnus renvoient tous active=false, de sorte que l’existence d’une adhésion ne fuite pas. Chaque système converge selon la fenêtre qu’il déclare, et en pratique la fenêtre d’écriture peut être plus courte que celle de lecture.

Si les périmètres ne suffisent pas, échouez localement

Chaque requête d’exécution porte des périmètres. Le SDK ne renvoie des identifiants utilisables que si les périmètres réellement accordés couvrent la requête ; sinon il échoue localement et n’envoie aucune requête métier. L’intérêt de cette règle est de séparer « la plateforme n’a pas autorisé » de « l’appel à la plateforme a échoué » : le premier est un problème de configuration qui doit être visible immédiatement, au lieu de se transformer en erreur amont opaque.

L’idempotence et les reprises reviennent à l’appelant

Le SDK ne réessaie jamais une requête de lui-même. Les opérations d’écriture doivent porter une clé d’idempotence stable fournie par l’appelant, et une requête échouée n’est pas renvoyée, car « résultat inconnu » et « échec » sont deux états distincts, et seul le système métier sait s’il faut renvoyer, interroger ou prévenir l’utilisateur. Côté erreurs, les Problem Details de la plateforme sont associés à des classes stables (non authentifié, interdit, conflit, limite de débit, erreur serveur, etc.) avec une indication de reprise possible, et les identifiants comme les corps de réponse n’atteignent jamais les journaux ni la sérialisation des erreurs.

Deux artefacts, deux voies d’obtention

Les deux SDK ne sont pas également accessibles : vérifiez d’abord lequel vous concerne. Côté TypeScript et Node, le paquet est @td-runlume/platform-integration-sdk sur npm public, Apache-2.0, pour un usage côté serveur. Côté Java, la coordonnée est app.runlume.platform:platform-integration-sdk-java, fournie depuis le dépôt Nexus de la plateforme et absente de Maven Central ; son usage est limité aux identifiants et à la licence accordés par la plateforme, et les artefacts ne doivent pas être redistribués. Les intégrations Java l’associent généralement au starter Spring Boot, qui assemble les composants du SDK et la chaîne de validité des sessions locales, le système métier ne fournissant que deux points d’extension : la frontière de session et la lecture de l’espace de travail.

Les chemins d’endpoint, les noms de périmètre et les capacités disponibles suivent le contrat et la documentation convenus à l’entrée en relation. Cet article ne traite que des limites que le serveur doit tenir ; les capacités elles-mêmes commencent par les capacités de la plateforme.