遠隔の業務システムをプラットフォームに接続するとき、つまずきやすいのは API 呼び出しそのものではなく、「誰がどの認証情報を持ち、それがいつ失効し、メンバーが外れてからどれくらいで反映されるか」です。この三つが、長く安定して動くかどうかを決めます。以下はその経路上で私たちが守っているやり方と境界です。

認証情報は二段階、長期のものはサーバーから出さない

プラットフォーム側の identity は二種類あります。モジュールサービス identity は長期の認証情報で、業務システムのサーバーだけが保持し、Launch Grant の交換（POST /integration/v1/sso/launch-grants/exchange）とインスタンスサービストークンの申請（POST /integration/v1/service-tokens）に使います。インスタンスサービストークンは、最長 5 分、Audience は固定、Scope は今回のリクエストに絞られた短期の認証情報で、no-store で返ります。

したがってブラウザーがモジュールの認証情報を受け取ることはありません。フロントエンドは受け取った Launch Code を自分のバックエンドに渡すだけで、交換はすべてサーバー側で行います。短期トークンについて SDK は「インスタンス + 今回のリクエストの Scope 集合」単位でキャッシュし、最長 300 秒、Refresh はありません。残りの寿命が安全ウィンドウを下回ると再取得し、同時呼び出しでも交換は一度だけ、インスタンスをまたいで再利用しません。

Launch は一度きりの交換で、得られるのは自分のセッション

ユーザーがプラットフォームから業務システムへ入るときに持つのは Launch Code で、長期の認証情報ではありません。バックエンドはモジュールサービス identity で Grant を交換して消費し、そのうえで業務システム自身のローカルセッションを確立します。セッションに入るのは派生した identity だけで、プラットフォームの Token、Launch Code、Client Secret、完全な Claims は入れません。

交換とセッション検証はいずれも署名検証を通します。プラットフォームのランタイム JWKS で署名アルゴリズム、Issuer、Audience、有効期間、token_use、Account と AppInstance、Scope を確認し、公開鍵の取得元はリダイレクトを禁止し、レスポンスサイズを制限します。混同しやすい点として、ログイン説明ページの「接続正常」は、バックエンドが公開鍵を解析できることだけを示します。ユーザーがログイン済みであることも、Launch 経路が使えることも示しません。三つは分けて扱ってください。

メンバーが外れたら、ローカルセッションを収束させる

プラットフォームのセッションが有効でも、ローカルセッションを無期限に使い続けられるわけではありません。長期セッションの間には、メンバーの削除、ロールの変更、インスタンスの停止が、限られた時間内に業務システムへ届く必要があります。方法はインスタンスサービス identity での一括検証（POST /integration/v1/session-checks）です。active が真になるのは、インスタンス、インスタンスメンバー、Account、Account メンバーがすべて有効な場合だけです。非メンバーと存在しないユーザーはどちらも active=false を返すため、メンバーの存在自体は漏れません。業務システムは自ら宣言した検証ウィンドウで収束させ、実務では書き込み側のウィンドウを読み取りより短くできます。

Scope が足りないときは、ローカルで失敗させる

実行時のリクエストはすべて Scope を持ちます。SDK が使える認証情報を返すのは、プラットフォームが実際に付与した Scope が今回のリクエストを覆う場合だけです。覆わなければローカルで失敗し、業務リクエストは送りません。この規則の意味は、「プラットフォームが許可していない」と「プラットフォーム呼び出しが失敗した」を切り分けることにあります。前者は設定の問題であり、すぐに見える必要があります。判読しにくい上流エラーに変えてはいけません。

冪等性と再試行は呼び出し側の責任

SDK はいかなるリクエストも自動で再試行しません。書き込み操作には呼び出し側が安定した冪等キーを渡し、失敗したリクエストは再送しません。「結果不明」と「失敗」は別の状態であり、再送すべきか、照会すべきか、ユーザーに伝えるべきかを知っているのは業務システムだけです。エラーについては、プラットフォームの Problem Details が安定した分類（未認証、権限なし、競合、レート制限、サーバーエラーなど）と再試行可否にマッピングされ、認証情報とレスポンス本文はログやエラーのシリアライズに入りません。

二つの成果物、二つの入手経路

二つの SDK は入手しやすさが異なるため、どちらに当てはまるかを先に確認してください。TypeScript / Node 側は public npm の @td-runlume/platform-integration-sdk で Apache-2.0、サーバー側での利用を想定しています。Java 側の座標は app.runlume.platform:platform-integration-sdk-java で、プラットフォームの Nexus リポジトリから提供され、Maven Central にはありません。利用はプラットフォームが付与した認証情報とライセンスの範囲に限られ、成果物を再配布しないでください。Java 側は通常 Spring Boot Starter と組み合わせ、SDK コンポーネントとローカルセッション有効性パイプラインは Starter が組み立て、業務システムはセッション境界とワークスペース参照の二つの拡張点だけを提供します。

エンドポイントのパス、Scope 名、利用できる機能は、契約時に合意した契約書とプラットフォームのドキュメントに従います。本記事はサーバー側が守る境界だけを扱います。機能の範囲はプラットフォーム機能から確認できます。