# 驗證與冪等性

SciFig API 每次呼叫所需的憑證、權限範圍、Idempotency-Key 和請求 ID。

來源：https://scifig.ai/zh-Hant/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 年；需要有效訂閱或大於零的點數包餘額 |

超出憑證權限範圍的請求回傳 `403 SCOPE_DENIED`。為每個應用程式和環境使用獨立金鑰，可單獨撤銷而不影響其他應用程式。

## 冪等性

- 每個建立請求（`POST /images/*`、`/charts/*`、`/flowcharts/*`）都需要 `Idempotency-Key` 請求標頭，長度為 1–255 個可見 ASCII 字元。每次請求使用隨機 UUID 最簡單。上傳至 `POST /files` 時也可傳送此請求標頭（參閱[檔案](/zh-Hant/docs/api/files#upload)）。
- 相同金鑰和相同請求體回傳同一個任務，不會再次預留點數。上傳圖表資料時，資料檔案的位元組也是請求體的一部分。
- 相同金鑰搭配不同請求體會回傳 `409 IDEMPOTENCY_CONFLICT`。使用相同金鑰的併發請求不會建立兩個任務：每個請求回傳同一個任務，或在首個請求仍被接納時回傳 `409 IDEMPOTENCY_IN_PROGRESS` 和 `Retry-After: 1`。
- 遇到超時、網路錯誤、`429` 或 `503` 時，請使用相同金鑰重試。這是確保不會重複建立任務的唯一方式。
- 任務已存在後，可重試錯誤（`429`、`503`、`409 IDEMPOTENCY_IN_PROGRESS`）或 `500 INTERNAL_ERROR` 會攜帶 `details.job_id`。請使用相同金鑰重試或輪詢 `GET /jobs/{job_id}`；不要換新金鑰，否則會建立並扣費第二個任務。任務已被接納但無法讀回時，回傳 `202` 和 `queued` 狀態。
- 被拒絕的請求（例如 `402 INSUFFICIENT_CREDITS`）會為該金鑰保留原響應。充值或升級後，請換新金鑰重新傳送。

## OAuth 用戶端

- MCP 用戶端使用帶 PKCE 的 OAuth 2.1。存取權杖（`sf_at_…`）有效期為 1 小時。請求 `offline_access` 權限範圍的用戶端還會收到有效期為 30 天的更新權杖（`sf_rt_…`），從而保持連線，直到你將其斷開；未請求 `offline_access` 時，存取權杖到期後需重新登入。
- 更新權杖採用輪換機制：每次更新都回傳新權杖。再次提交已使用的更新權杖會被視為重複使用，並撤銷由它簽發的權杖，用戶端需重新登入。
- 動態用戶端註冊接受最多 16 KB 的請求體，同時限制各欄位長度和重定向 URI 數量。權杖端點驗證方式為 `none`（使用 PKCE 的公共用戶端）或 `client_secret_basic`。
- 註冊後從未獲得授權的用戶端會在 24 小時後刪除。
- 攜帶 `prompt=login` 或 `max_age` 的授權請求要求重新登入。如果你已登入，SciFig 會先請你確認，再退出並重新登入。
- OAuth 憑證的速率限制按用戶端和帳戶計算，同一助手的其他使用者不會佔用你的額度。

## 請求 ID

每個響應都帶有 `X-Request-Id`；錯誤響應體也會在 `error.request_id` 中回傳它。它可在日誌中標識請求，不暴露其他資訊，因此可以安全地記錄，並在聯絡支援時提供。