# 鉴权与幂等性

SciFig API 每次调用所需的凭据、权限范围、Idempotency-Key 和请求 ID。

来源：https://scifig.ai/zh/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/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` 中返回它。它可在日志中标识请求，不暴露其他信息，因此可以安全地记录，并在联系支持时提供。