# 認証と冪等性

SciFig API の各呼び出しで使う認証情報、スコープ、Idempotency-Key、リクエスト ID。

出典：https://scifig.ai/ja/docs/api/authentication

## Bearer 認証

`GET /pricing`、`GET /openapi.json`、`GET /openapi.yaml` 以外の各リクエストに `Authorization: Bearer <credential>` を送信します。クエリパラメーターやその他のヘッダーに入れた認証情報は無視されます。

認証情報は Bearer 認証を使用します。DPoP に紐付けた認証情報はサポートしていません。

- API キーは `sk_live_` で始まります。設定 → 開発者で作成すると、キーは一度だけ表示されます。サーバーに保管し、ブラウザーやモバイルアプリに組み込まないでください。有効期限の 7 日前にメールでお知らせします。
- OAuth アクセストークンは `sf_at_` で始まります。クライアントを承認すると MCP クライアントに発行されます。設定 → 開発者 → 接続済みアプリからクライアントの接続を解除できます。
- 認証情報が未指定、無効、期限切れ、または失効済みの場合は `401 UNAUTHORIZED` を返します。API を利用できないアカウント（削除処理中など）は `401 ACCOUNT_UNAVAILABLE` を返します。
- キーを失効させると、そのキーによる新しいリクエストは停止します。作成済みのジョブは引き続き実行され、同じアカウントの別の認証情報で読み取れます。

## スコープ

| スコープ | 付与される権限 | API キーの種類 |
| --- | --- | --- |
| figures:read | `GET /jobs`, `GET /jobs/{id}`, `GET /files/{file_id}`, `GET /credits` | 読み取り専用キー。有効期限なしも設定可能 |
| figures:generate | `figures:read` のすべての権限と、すべての `POST` エンドポイント | 生成用キー。有効期間は 30 日、90 日、1 年。有効なサブスクリプション、または残高が 0 を超えるクレジットパックが必要 |

認証情報のスコープ外のリクエストは `403 SCOPE_DENIED` を返します。アプリケーションや環境ごとにキーを分けると、他に影響を与えずに個別のキーを失効できます。

## 冪等性

- すべての作成リクエスト（`POST /images/*`、`/charts/*`、`/flowcharts/*`）には、表示可能な ASCII 文字 1～255 文字の `Idempotency-Key` ヘッダーが必要です。リクエストごとにランダムな UUID を使うのが簡単です。`POST /files` へのアップロードにも指定できます（[ファイル](/ja/docs/api/files#upload)を参照）。
- 同じキーと同じ本文で送信すると、同じジョブを返し、クレジットを再度確保することはありません。グラフのアップロードでは、データファイルのバイト列も本文に含まれます。
- 同じキーで本文が異なると `409 IDEMPOTENCY_CONFLICT` を返します。同じキーの同時リクエストが 2 件のジョブを作成することはありません。それぞれが同じジョブを返すか、最初のリクエストの受け付け処理中は `Retry-After: 1` 付きの `409 IDEMPOTENCY_IN_PROGRESS` を返します。
- タイムアウト、ネットワークエラー、`429`、`503` の後は同じキーで再試行してください。ジョブの重複作成を確実に防ぐには、この方法が必要です。
- ジョブの作成後は、再試行可能なエラー（`429`、`503`、`409 IDEMPOTENCY_IN_PROGRESS`）や `500 INTERNAL_ERROR` に `details.job_id` が含まれます。同じキーで再試行するか、`GET /jobs/{job_id}` でポーリングしてください。新しいキーに切り替えると、別のジョブが作成され、再び課金されます。受け付け済みのジョブを読み戻せなかった場合は、ステータス `queued` の `202` を返します。
- 拒否されたリクエスト（`402 INSUFFICIENT_CREDITS` など）は、そのキーに同じ応答を保持します。チャージやアップグレードの後は、新しいキーで再送してください。

## OAuth クライアント

- MCP クライアントは PKCE を伴う OAuth 2.1 を使用します。アクセストークン（`sf_at_…`）は 1 時間有効です。`offline_access` スコープを要求するクライアントには、30 日間有効なリフレッシュトークン（`sf_rt_…`）も発行され、接続を解除するまで接続を維持できます。`offline_access` がなければ、アクセストークンの有効期限が切れたときに再ログインが必要です。
- リフレッシュトークンは更新のたびに新しく発行されます。使用済みのリフレッシュトークンを提示すると再使用と見なされ、そのトークンから発行されたトークンは失効し、クライアントは再ログインが必要になります。
- 動的クライアント登録の本文は最大 16 KB です。各フィールドの長さとリダイレクト URI の数にも制限があります。トークンエンドポイントの認証方式は、PKCE を使う公開クライアント向けの `none`、または `client_secret_basic` です。
- 登録後、一度も承認されていないクライアントは 24 時間後に削除されます。
- `prompt=login` または `max_age` を伴う認可リクエストは、新たなログインを要求します。すでにログインしている場合は、SciFig が確認を求めてから、一度ログアウトして再ログインする流れに進みます。
- OAuth 認証情報のレート制限はクライアントとアカウントごとに集計されるため、同じアシスタントを使う他のユーザーがあなたの制限枠を消費することはありません。

## リクエスト ID

すべてのレスポンスに `X-Request-Id` が付き、エラー本文には `error.request_id` として再掲されます。ほかの情報を開示せずにログ内のリクエストを特定できるため、ログへの記録やサポートへの連絡に安全に利用できます。