コンテンツにスキップ

Figmaトークン状態の取得

2026-08-20 追加

wf2desの生成処理がリクエストしたユーザー自身のFigma PATを使用する方式へ移行したことに伴い追加された。クライアントはGenerateを提示する前にトークン入力を促す必要があるかを判断しなければならない。トークンが未登録の場合、生成トリガーは不透明な500で失敗するためである（POST /wf2desを参照）。

メソッド

RESTメソッドを採用する。

HTTPメソッド

GET: 認証済みの呼び出し元にFigma Personal Access Tokenが登録されているかを返す。

命名規則

レスポンスのJSONノードはcamelCaseであり、POST /figma/tokenと一致する。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

  • Authorization — 必須、Cognito JWT
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

トークン状態の取得

URI

GET /figma/token

パスパラメータ、クエリパラメータ、ボディパラメータはない。対象は常に認証済みの呼び出し元であり、他ユーザーのトークン状態を照会する手段は存在しない。

レスポンス

レスポンスはJSONである。

{
  "registered": true,
  "lastValidatedAt": 1746576000000,
  "updatedAt": 1746576000000
}

レスポンスフィールド

名前 型 説明
registered boolean 呼び出し元のcognito_subに対応する行が存在する場合はtrue
lastValidatedAt number | null GET https://api.figma.com/v1/meによる最後の検証成功時刻（エポックミリ秒）。未登録の場合はnull
updatedAt number | null 行が最後に書き込まれた時刻（エポックミリ秒）。未登録の場合はnull

未登録の場合、本エンドポイントは404ではなく200を返す:

{
  "registered": false,
  "lastValidatedAt": null,
  "updatedAt": null
}

「トークン未登録」はまだ設定していないユーザーにとって正常な状態であり、エラーではない。クライアントは失敗としてではなく、入力を促す表示としてレンダリングすべきである。

トークン自体は決して返さない

本エンドポイントは登録有無とタイムスタンプのみを返す。保存されたPATは設計上write-onlyであり、返却してしまえばセッションを保持する者にとって読み取り可能な秘密情報に変わってしまう。ハンドラはリポジトリ経由で（復号して）読み出すが、メタデータのみを返す。

認証

Cognito JWT。レスポンスは認証済みのcognito_subに紐づくトークンについて記述する。

エラーハンドリング

説明 ステータスコード ステータス名
Cognito JWTが欠落または無効 401 Unauthorized
サーバー内部エラー 500 Internal Server Error

処理フロー

  1. Cognito JWTで呼び出し元を認証し、cognito_subを取得する。
  2. そのcognito_subに対応するfigma_token行を検索する。
  3. registered、lastValidatedAt、updatedAtを返す。トークン自体は返さない。

クライアント向けガイダンス

Figmaプラグインはセットアップパネルで本エンドポイントを呼び出し、「トークン登録済み」のピル表示とパスワード入力欄のどちらを表示するかを判断する。これにより、デザイナーはGenerate時に500に遭遇するのではなく、その場で問題を解決できる。

なおregistered: trueはトークンが現在も有効であることを保証しない。lastValidatedAtはFigmaが最後にそのトークンを受け入れた時刻を記録するものであり、PATはその後に期限切れまたは失効し得る。失効したトークンは生成時に判明し、POST /figma/tokenで再登録することで再検証される。

関連