コンテンツにスキップ

Figma 連携（コールバック）

メソッド

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

HTTP メソッド

GET: 管理者がアプリを認可した後の Figma からのリダイレクトを受け取り、認可コードを交換してグラントを保存します。

Figma は管理者の ブラウザ をここへリダイレクトします。プラグインや当社の他のクライアントから呼ばれることはありません。

命名規則

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

リクエストとレスポンス

ヘッダー

リクエストヘッダー

必須のものはありません — 認証 を参照してください。

レスポンスヘッダー

  • Content-Type

コールバック

URI

GET /api/v1/figma-oauth/callback

パスに {organization_id} セグメントはありません: redirect_uri は Figma アプリに登録された URL と完全一致する必要があるため固定です。組織 ID は代わりに state の中を通ります。

クエリパラメータ

名前 型 必須 説明
code string 任意 認可コード。管理者が拒否した場合は存在しない。発行から 30 秒で失効する。
state string 必須 authorize が発行した署名済みトークン。組織 ID を含む。
error string 任意 管理者が Figma 側で拒否した場合に付与される。

レスポンス

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

{
  "organizationId": 1,
  "connected": true,
  "message": "Figma connected. The scheduler will refresh this organization grant automatically."
}

レスポンスフィールド

名前 型 説明
organizationId integer グラントを保存した組織。state から読み取られる。
connected boolean 成功時は常に true。
message string ブラウザタブに表示する確認メッセージ。

トークンは呼び出し元へ 決して 返されず、ログにも出力されません。

認証

ありません — そして持たせることができません。 これは Figma からのブラウザリダイレクトであり、Cognito トークンを伴わないため protectedRoute では保護できません。

したがって state がセキュリティ境界のすべてです: 認証済みの組織管理者によってサーバー側で発行され、HMAC 署名され、組織に紐づき、用途が単一で、有効期間は 10 分、署名比較は 定数時間 で行われます。組織 ID は 署名済みペイロード から読み取られ、呼び出し元が指定した値からは決して読み取りません。

これが無ければ、この URL に到達できる者は誰でも自分の Figma グラントをあなたの組織に紐づけられ、スケジューラが読めるものすべてを自らに与えられてしまいます。

署名エラーと不正な入力は同一のメッセージを返すため、このエンドポイントは偽造の試行に対する判定オラクルになりません。

エラーハンドリング

説明 ステータスコード ステータス名
管理者が Figma 側で拒否した、または code が返らなかった 400 Bad Request
Figma がコードを拒否した（30 秒で失効するため、最初からやり直す） 400 Bad Request
state が不正・改ざん・期限切れ 401 Unauthorized
グラントの暗号化または保存に失敗 500 Internal Server Error

処理フロー

  1. error が存在する場合、管理者が拒否したということ — その旨を報告して終了する。
  2. state を検証する: 定数時間での署名検証、有効期限の確認、署名済みペイロードからの organizationId の復元。
  3. https://api.figma.com/v1/oauth/token で HTTP Basic client_id:client_secret を用いて code を交換する。クライアントシークレットは Admin API が保持する。
  4. アクセストークンとリフレッシュトークンをプラットフォームの ENCRYPTION_KEY で暗号化し、組織の figma_oauth_grant 行を PostgreSQL に upsert する。
  5. どの Figma アカウントが認可したかを記録し（監査用）、確認レスポンスを返す。

その後

これ以上の作業は不要です。wf2des が Figma へアクセスする際は、IAM で保護された Admin API の内部 token provider を呼び出します。Admin API は既存のアクセストークンを返すか、PostgreSQL advisory lock のもとでリフレッシュし、アクセストークンと有効期限だけを返します。ワーカーは Authorization: Bearer で Figma を呼び出します。

再び人手が必要になるのは、Figma 側でグラントが失効された場合、サービスアカウントが無効化された場合、クライアントシークレットをローテーションした場合、暗号鍵をローテーションした場合 のみ です。