密钥的权限范围
权限范围指定密钥可以调用 API 的哪一部分。API 参考中的每个接口都声明了它需要的一个权限范围。如果请求所用的密钥缺少该权限范围，请求会在读取或更改任何内容之前被拒绝，返回 403，错误码为 api_keys.scope。
权限范围决定密钥可以调用哪些操作。这些操作能看到哪些对象，仍由密钥的角色、数据权限档案和合集决定：具有 cards:write 且角色为 viewer 的密钥不能更改卡片，仅限一个合集的密钥看不到其他合集。
权限范围列表
| 权限范围 | 允许的操作 |
|---|---|
cards:read | 读取卡片、合集和文件夹。 |
cards:write | 创建、更改和删除卡片、合集和文件夹。 |
search | 搜索知识库（POST /v1/search）。 |
ask | 向助手提问（POST /v1/ask、POST /v1/chat）。 |
import:write | 写入组织的自定义数据源：同步、批次和删除，并读取它们的状态。创建数据源及其密钥需要 admin。 |
webhooks:manage | 管理 Webhook，读取事件记录（GET /v1/webhook-events）。两者都还需要 admin 角色。 |
users:read | 读取用户和用户组。 |
users:write | 更改用户和用户组。 |
analytics:read | 读取分析数据。 |
audit:read | 读取审计日志。 |
finance:read | 读取财务报告、发票和付款。 |
catalog:read | 读取服务目录。 |
files:read | 读取生成的文件，例如导出的回答。 |
files:write | 更改和删除生成的文件。 |
permissions:manage | 授予和撤销对象上的权限。 |
admin | 组织的设置及其 API 密钥。具有 admin 的密钥同时拥有所有其他权限范围。 |
按语义，搜索和提问属于读取：只能读取的密钥仍然可以搜索和提问。
选择权限范围
只授予集成用到的权限范围，不多给：
| 集成 | 权限范围 |
|---|---|
| 聊天工具中的问答机器人 | search、ask |
| 从您的文档系统导入 | cards:write（卡片 API）或 import:write（自定义数据源） |
| 导出到数据仓库 | cards:read、users:read，以及用于读取事件记录的 webhooks:manage |
| 从 HR 系统开通用户 | users:write |
创建密钥时传入列表：
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'旧版权限范围
在权限范围拆分之前创建的密钥仍然有效。它们的权限范围 read、write 和 admin 分别代表以下集合：
| 旧版权限范围 | 含义 |
|---|---|
read | cards:read、search、ask、users:read、analytics:read、finance:read、catalog:read、files:read |
write | read 的全部权限范围，外加 cards:write、files:write、users:write、permissions:manage |
admin | 所有权限范围 |
创建时未明确指定权限范围的密钥按其角色获得权限范围：admin 获得 admin；editor 和 verifier 获得 write；viewer 获得 read。
查看密钥的权限范围
GET /v1/me 返回发出请求的密钥的权限范围，无论这些权限范围是如何获得的。对于创建时没有明确指定权限范围的密钥，返回的是其角色对应的旧版权限范围，例如 read 和 write；它们代表什么，见上表。操作因 api_keys.scope 失败时，error.message 会指出缺少的权限范围。