API 密钥与权限范围

发往 Sursa API 的每个请求都使用您组织的 API 密钥。密钥属于组织，而不属于某个人：创建密钥的员工离职后，密钥照常有效；密钥能做什么，由密钥本身的设置决定。

密钥允许做什么

密钥的三项设置决定使用它的请求能看到和更改什么。每一项都只会进一步缩小其他各项的范围。

还可以把密钥限制在部分合集内，并设置过期日期。超出这些限制的请求会失败：缺少权限范围时返回 403，错误码为 api_keys.scope；密钥看不到的对象返回 404，与对象不存在时完全一样。

为每个集成单独创建一个密钥，只授予所需的最小角色和权限范围。只写入文档的同步作业不需要 admin；生成报表的作业不需要写入类的权限范围。

创建密钥

组织管理员可以在 Sursa 的 Administration → API keys（管理 → API 密钥）中创建密钥，也可以使用具有 admin 角色的密钥或会话调用 POST /v1/api-keys：

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

响应的 key 中包含密钥的值。它只显示一次：Sursa 只保存它的哈希值，无法再次显示。密钥的形式是 kb_ 后跟 43 个字符；密钥列表中显示开头的几个字符（prefix），便于区分不同的密钥。

不传 scopes 时，密钥获得其角色对应的权限范围。传入 scopes 可以进一步缩小范围。不传 expires_at 时，密钥永不过期。

妥善保管密钥

• 把密钥保存在密钥管理服务或服务的环境变量中，绝不要写进源代码。
• 只在服务器上使用密钥。Sursa 接受来自浏览器的请求（CORS 是开放的），但网页中的密钥对所有打开该网页的人都可见。
• 绝不要在 URL 中传递密钥，只在 Authorization 头中传递。
• 密钥泄露时，立即撤销它并创建一个新密钥。

检查密钥

GET /v1/me 返回密钥本身及其角色、实际权限范围、数据权限档案、过期时间和速率限制。任何有效的密钥都可以调用它，无论密钥有哪些权限范围，因此可以用它测试集成的连接，也可以在排查 403 时使用。

轮换密钥

轮换可以在不中断集成的情况下替换密钥。最快的方法是重新生成密钥：POST /v1/api-keys/{key_id}/roll 为同一个密钥签发新值，角色、权限范围、合集和过期日期保持不变。旧值在 overlap_hours 内仍然有效（默认 24 小时，最多 168 小时），这段时间内可以部署新值；POST /v1/api-keys/{key_id}/revoke-previous 可以提前结束过渡期。

要改用另一个密钥替换原密钥：

1. 创建一个角色、权限范围和数据权限档案都相同的新密钥。
2. 把新密钥部署到集成中。
3. 在 Administration → API keys 中（或通过 GET /v1/api-keys 中的 last_used）观察旧密钥，直到它不再被使用。
4. 撤销旧密钥。

为密钥设置过期日期，并在到期前轮换。密钥过期前，Sursa 会提醒组织管理员；过期的密钥返回 401，错误码为 api_keys.expired。

撤销密钥

在 Administration → API keys 中撤销密钥，或调用 DELETE /v1/api-keys/{key_id}。撤销在几秒内对所有 API 服务器生效。使用已撤销密钥的请求返回 401，错误码为 auth.not_authenticated。

自定义数据源的密钥

自定义数据源有自己的一类密钥。这类密钥以 kbsrc_ 开头，只能向所属的那一个数据源写入文档，不能读取或搜索任何内容。把密钥交给 Zapier 这样的集成平台时，它是最安全的选择。在数据源页面的 API keys（API 密钥）区块中创建，或调用 POST /v1/sources/{source_id}/push-keys。

无法使用密钥时

API 密钥是组织套餐的一部分。如果套餐不包含 API 密钥，创建密钥以及使用密钥的每个请求都会返回 403，错误码为 api_keys.feature_disabled。