Figma Personal Access Token 登録

2026-05-07 に OAuth から移行

旧 GET /figma/oauth、GET /figma/oauth/token、POST /figma/oauth/refresh の各エンドポイントを置き換える。ユーザーは Figma 設定画面で PAT を生成し、OAuth リダイレクトを経由せず本エンドポイントへ直接送信する。

メソッド

RESTメソッドを採用しています。

HTTPメソッド

POST: ユーザーの Figma Personal Access Token を検証して保存する。

命名規則

クエリパラメータとノードの命名を統一し、可読性を向上させるため、リクエスト時のURIとJSON内のノードには snake_case を使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTPヘッダー に設定されます。

リクエストヘッダー

Authorization — 必須、Cognito JWT
Content-Type — application/json
Accept
Accept-language

レスポンスヘッダー

Content-Type

PAT 登録

URI

POST /figma/token

リクエストボディ

{
  "personal_access_token": "<figma-pat>"
}

リクエストフィールド

名前	型	必須	説明
personal_access_token	string	必須	ユーザーが貼り付けた Figma PAT。空文字不可、最大 256 文字、空白を含まないこと

レスポンス

レスポンスは JSON です。

{
  "cognitoSub": "user-cognito-sub",
  "lastValidatedAt": 1746576000000,
  "createdAt": 1746576000000,
  "updatedAt": 1746576000000,
  "createdBy": "user-cognito-sub",
  "updatedBy": "user-cognito-sub"
}

レスポンスフィールド

名前	型	説明
cognitoSub	string	ユーザーの Cognito 識別子
lastValidatedAt	number	`GET /v1/me` 検証成功時刻（エポックミリ秒、任意）
createdAt	number	作成日時（エポックミリ秒）
updatedAt	number	更新日時（エポックミリ秒）

PAT 本体は登録後のいかなるレスポンスにも 含めない。返却されるのは保存済み行のメタ情報のみ。

認証

認証は Amazon Cognito から発行される JSON Web Tokens (JWT) を使用して行われます。PAT は認証済みユーザーの cognito_sub に紐づけて保存されます。

例外処理

説明	ステータスコード	ステータス名	エラーコード
バリデーション失敗（形式 / 空 / 空白）または Figma `GET /v1/me` で 401/403 が返された	400	Bad Request	`invalid_figma_token`
Cognito JWT の不在 / 不正	401	Unauthorized
リクエスト制限超過	429	Too Many Requests
内部サーバーエラー	500	Internal Server Error
Figma API 到達不可 / 5xx	502	Bad Gateway

GET /v1/me 呼び出し時に Figma 側から 429 が返却された場合、Figma の Retry-After ヘッダーをそのままクライアントに伝搬する。

処理フロー

Cognito JWT で呼び出し元を認証し、cognito_sub を取得する
personal_access_token の形式を検証（空文字不可、≤256 文字、空白を含まない）。不正なら 400 invalid_figma_token
GET https://api.figma.com/v1/me を X-Figma-Token: <pat> ヘッダー付きで呼び出す
200 → 続行
401 / 403 → 400 invalid_figma_token
429 → Figma の Retry-After を引き継いで 429 を返す
5xx → 502
PAT を AES-256 で暗号化し、cognito_sub を主キーに figma_token テーブルへ upsert する。last_validated_at を現在時刻に設定
上記レスポンス JSON を返却

レート制限

このエンドポイントはレート制限されています: - 制限: 1 分間に 10 リクエスト - 範囲: ユーザーごと（Cognito sub で識別）

セキュリティ

PAT は AES-256 で暗号化保存する
登録後の API レスポンスには PAT を含めない
ログ / トレースでは PAT をマスクし、cognito_sub と検証結果のみを残す
旧 PAT の取り消しはユーザー自身が Figma 設定画面で行う

詳細フローチャート

flowchart TD
    Start([POST /figma/token]) --> Auth[Cognito JWT 認証]
    Auth --> AuthOK{有効な JWT?}
    AuthOK -->|No| Err401[401 Unauthorized]
    AuthOK -->|Yes| Validate[PAT 形式検証]
    Validate --> FormatOK{形式 OK?}
    FormatOK -->|No| Err400[400 invalid_figma_token]
    FormatOK -->|Yes| CallMe[GET https://api.figma.com/v1/me<br/>X-Figma-Token: PAT]
    CallMe --> FigmaResp{Figma レスポンス}
    FigmaResp -->|401/403| Err400
    FigmaResp -->|429| Err429[429 Too Many Requests<br/>Retry-After 引き継ぎ]
    FigmaResp -->|5xx| Err502[502 Bad Gateway]
    FigmaResp -->|200| Encrypt[PAT を AES-256 で暗号化]
    Encrypt --> Upsert[figma_token に upsert<br/>cognito_sub をキー]
    Upsert --> Success[200 OK]