コンテンツにスキップ

Figma 連携（認可 URL の発行）

メソッド

この API は REST の方法論に従います。

HTTP メソッド

POST: 組織管理者が開く Figma の同意 URL を発行します — wf2des スケジューラ が動作するための Figma OAuth アプリの認証情報を接続する操作です。

これは意図的な一度きりのセットアップ操作であり、プラグインのログインの一部では ありません。この API が存在する理由 を参照してください。

命名規則

一貫性と可読性のため、リクエスト / レスポンスの JSON ノードは camelCase を使用します。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

  • Authorization
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

認可 URL の発行

URI

POST /api/v1/organizations/{organization_id}/figma-oauth/authorize

パスパラメータ

名前 型 必須 説明
organization_id integer 必須 組織 ID

リクエストボディ

なし。

レスポンス

レスポンスは JSON です（HTTP ステータス: 200 OK）。

{
  "authorizeUrl": "https://www.figma.com/oauth?client_id=…&redirect_uri=…&scope=file_content%3Aread&state=…&response_type=code",
  "expiresInSeconds": 600
}

レスポンスフィールド

名前 型 説明
authorizeUrl string Figma の同意 URL。署名済み・有効期限付き・組織に紐づいた state を含む。
expiresInSeconds integer このリンクが有効な秒数（600）。超過した場合は再発行する。

サービスアカウントでサインインした状態で開くこと

authorizeUrl は シークレット/プライベートウィンドウ で、専用の Figma サービスアカウントとしてサインインした状態で開いてください — 自分自身の Figma ユーザーではいけません。管理者自身でサインイン済みのブラウザで開くと、グラントは その個人 に紐づきます。見た目は成功しますが、まさに本機能が解消しようとしている依存関係が復活し、その人が権限を変更したり退職した時点でスケジューラが停止します。

サービスアカウントに Figma ファイルへのアクセス権が必要です

OAuth グラントは 認可したアカウントが既に見られるものだけ を引き継ぎます。サービスアカウントが プロジェクトで使う Figma のチームやファイルに招待されていない場合、Figma への読み取りはすべて 403 Request denied を返します。グラント自体は有効なため、権限不足ではなく連携の不具合のように見えます。

実測で確認: 同一ファイル・同一リクエストに対し、アクセス権を持つアカウントの PAT は 200、 アクセス権のないアカウント向けに発行したばかりのグラントは 403 を返しました。接続の 前に サービスアカウントを対象ファイル（またはそのチーム）へ招待し、接続後はファイル読み取りで確認してください。

認証

Admin Cognito プールが発行する JWT と、組織レベルの read/write 権限が必要です。組織全体の認証情報を確立するため、通常のアプリユーザーやプロジェクトオーナーは置き換えできません。

エラーハンドリング

説明 ステータスコード ステータス名
認証情報の欠落 401 Unauthorized
管理者ロールに組織 read/write 権限がない 403 Forbidden
組織が存在しない 404 Not Found
このデプロイで Figma OAuth が未設定 500 Internal Server Error

500 のメッセージは FIGMA_OAUTH_CLIENT_ID / FIGMA_OAUTH_CLIENT_SECRET / FIGMA_OAUTH_REDIRECT_URI / FIGMA_OAUTH_STATE_SECRET のどれが欠けているかを明示します — 4 つすべてが揃って初めて有効です。

処理フロー

  1. パスパラメータから組織 ID を取得する。
  2. Admin Cognito セッションと組織 read/write 権限を検証する。
  3. state を発行する — 署名済み・組織に紐づく・10 分間有効なトークン（重要性は callback を参照）。
  4. client_id、登録済みの redirect_uri、scope=file_content:read、state、response_type=code を含む Figma 同意 URL を組み立てる。
  5. URL を返す。この時点では何も保存されない。

この API が存在する理由

スケジュール実行される component_sweep はボディなしの EventBridge 呼び出しです — ユーザーもリクエストも無く、テナンシーもデフォルト組織以外にありません。パーソナルアクセストークンではこれを担えません: 特定個人の恒常的な権限であり、こちらで制御できる有効期限を持たず、そもそもワーカーは PostgreSQL クライアントを持たないためプラットフォームの figma_token テーブルに到達できません。

Figma は authorization code フローのみ をサポートし、client-credentials / machine-to-machine グラントは存在しません。したがってヘッドレス実行が自ら認証情報を発行することは不可能です。人手による手順はちょうど 1 回だけ必要で、それがこのエンドポイントです。以降の自動リフレッシュは Admin API が行い、ワーカーは有効なアクセストークンだけを Admin API から取得します。

クライアントシークレットだけでは不十分です: それは アプリの身元 を示すものであり、誰かのファイルを読む権限そのものではありません。