驗證與冪等性

除 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。
• 撤銷金鑰會阻止使用該金鑰的新請求；此前建立的任務繼續執行，同一帳戶的其他憑證仍可讀取這些任務。

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

• 每個建立請求（POST /images/*、/charts/*、/flowcharts/*）都需要 Idempotency-Key 請求標頭，長度為 1–255 個可見 ASCII 字元。每次請求使用隨機 UUID 最簡單。上傳至 POST /files 時也可傳送此請求標頭（參閱檔案）。
• 相同金鑰和相同請求體回傳同一個任務，不會再次預留點數。上傳圖表資料時，資料檔案的位元組也是請求體的一部分。
• 相同金鑰搭配不同請求體會回傳 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）會為該金鑰保留原響應。充值或升級後，請換新金鑰重新傳送。

• 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 憑證的速率限制按用戶端和帳戶計算，同一助手的其他使用者不會佔用你的額度。

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