鉴权与幂等性

除 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 中返回它。它可在日志中标识请求，不暴露其他信息，因此可以安全地记录，并在联系支持时提供。