Authentication

概要

Supervity プラットフォームは Keycloak ID プロバイダーが発行する JWT（JSON Web Token） を使用します。すべてのユーザー向けエンドポイントには有効な JWT トークンが必要です。

トークンの提供方法

トークンは次の 3 通りで提供できます（この順序で確認されます）。

1. Cookie（ブラウザクライアント向け推奨）

2. クエリパラメータ（ヘッダーが制限される SSE ストリーム向け）

3. Authorization ヘッダー（サーバー間または API クライアント向け推奨）

4. カスタム API キー（外部 API アクセス向け）

プログラムからのアクセスには、Developer Settings からカスタム API キーを生成できます。API キー使用時は、外部キーとして正しく識別するため x-source: external ヘッダーも必須です。

組織コンテキスト（x-active-org）

ほとんどのエンドポイントには アクティブな組織コンテキスト が必要です。x-active-org リクエストヘッダーで指定します。

省略した場合、サーバーはデータベースからユーザーが以前保存した組織設定を参照します。初回アクセス時、組織キーは JWT クレームから導出されます。

ベストプラクティス： 曖昧さを避けるため、すべてのリクエストで x-active-org を明示的に含めてください。

認証付きリクエストの例

トークンクレーム

JWT ペイロードには、サーバーが使用する以下の関連フィールドが含まれます。

エラーレスポンス

レート制限

• 制限: IP アドレスあたり毎分 60 リクエスト
• バックエンド: Redis ベースのスライディングウィンドウ
• 除外: プライベート/内部 IP アドレス
• 制限時のヘッダー: 429 レスポンスに Retry-After: <seconds> が含まれます

CORS

許可オリジンは CORS_ALLOW_ORIGIN 環境変数でサーバー側設定されます。ブラウザクライアントはそのオリジンから配信される必要があります。

チームベースのアクセス制御

リソース（ワークフロー、スレッド）はチームと共有できます。サーバーは JWT のチームメンバーシップクレームに基づきチームゲートフィルタリングを自動適用します。どのチームとも共有されていないリソースはオーナーのみが閲覧できます。