身份验证
发往 Sursa API 的每个请求都在 Authorization 头中带有 API 密钥或应用的 OAuth 访问令牌：
Authorization: Bearer kb_3f9c…
密钥确定请求属于哪个组织，以及请求能看到和更改哪些内容：密钥的角色、权限范围、数据权限档案和合集。API 专用地址上没有会话，也不使用 Cookie。每个请求单独进行身份验证，因此可以用同一个密钥并行发送请求，也可以从多台服务器发送。
curl https://api.sursa.com/v1/me \
-H "Authorization: Bearer $SURSA_API_KEY"早期的集成可能改用 X-API-Key 头传入密钥。这种方式仍然有效，但新代码应使用 Authorization: Bearer。
凭据的种类
| 凭据 | 格式 | 适用范围 |
|---|---|---|
| 组织 API 密钥 | kb_… | API 的所有接口，受密钥的角色、权限范围、数据权限档案和合集限制。 |
| 自定义数据源密钥 | kbsrc_… | 仅限所属自定义数据源的推送接口（/v1/push/sources/{source_id}/…）。 |
| OAuth 访问令牌 | kbat_… | API 参考中的接口，受令牌的权限范围限制。通过授权码从 POST /oauth/token 获得的令牌代表给予授权同意的员工执行操作；client_credentials 令牌与 API 密钥一样代表组织执行操作。令牌的有效期为 1 小时。 |
所有凭据的传入方式都相同。自定义数据源密钥不能读取、搜索或更改所属数据源以外的任何内容；密钥需要交给第三方保存时（例如集成平台），请使用这种密钥。
身份验证错误
| 状态和错误码 | 含义 | 处理方法 |
|---|---|---|
401 auth.not_authenticated | 没有密钥、密钥输错或密钥已撤销。 | 检查请求头和密钥的值。 |
401 api_keys.expired | 密钥已过有效期。 | 创建新密钥，替换旧密钥。 |
401 sources.push_key_invalid | 自定义数据源密钥有误、已撤销或属于其他数据源。 | 检查密钥和路径中的数据源 ID。 |
401 oauth.token_expired | OAuth 访问令牌已过期。 | 用刷新令牌获取新的访问令牌。 |
403 api_keys.scope | 密钥没有执行此操作所需的权限范围。 | 添加权限范围，或改用具有该权限范围的密钥。 |
403 api_keys.feature_disabled | 组织的套餐不包含 API 密钥。 | 联系组织管理员。 |
403 api_keys.ip_not_allowed | 请求来自密钥允许的地址以外的地址。 | 从允许的网络调用，或更改密钥允许的地址。 |
403 api_keys.mcp_only | 在 /mcp 接口之外使用了个人 MCP 密钥。 | 调用 API 请使用组织 API 密钥。 |
403 oauth.operation_not_allowed | 该操作不属于公开 API，因此 OAuth 令牌不能调用。 | 使用 API 参考中的操作。 |
403 org.suspended | 组织已被暂停，数据仍然保留。 | 联系组织管理员。 |
403 表示请求已通过身份验证，但不被允许。密钥无权查看的对象返回 404，与不存在的对象相同，因此密钥无法得知其访问范围以外有什么。
以数据权限档案的身份发出请求
具有 admin 角色的密钥可以检查另一组人会看到什么：X-View-As 头让请求以某个数据权限档案的身份执行，还可以指定角色。
curl "https://api.sursa.com/v1/cards?limit=20" \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "X-View-As: employee:viewer"这种模式下的请求只能读取：任何更改都会返回 403，错误码为 view_as.read_only。OAuth 令牌和没有 admin 角色的密钥不能使用 X-View-As：请求返回 403，错误码为 view_as.admin_key_required。请求头中指定的数据权限档案不存在时，返回 400，错误码为 view_as.invalid_header。
浏览器应用
API 允许来自任何 Web 源的请求（Access-Control-Allow-Origin: *），且从不使用 Cookie，因此页面可以用 fetch 调用 API。这时密钥存放在页面中，所有使用该页面的人都能看到。只有当密钥可以公开给这些用户时，才从浏览器调用 API，例如仅限公开合集的 viewer 密钥；否则请在浏览器和 Sursa 之间放一台自己的服务器。
只有员工才能执行的操作
组织 API 密钥代表组织执行操作，而不是代表某个人。API 中有两部分属于个人，因此只能使用代表员工执行操作的令牌：Sursa 中的会话，或经员工授权同意后签发的 OAuth 访问令牌。
对话属于个人。组织 API 密钥在 GET /v1/conversations 中只能看到它自己发起的对话。公开 API 中没有发起对话的操作，因此对密钥来说，这个列表通常为空，员工的对话永远不会向密钥显示。不在对话中的提问使用 POST /v1/ask 或 POST /v1/chat，任何具有 ask 权限范围的密钥都可以调用。要列出某位员工的对话，并用 GET /v1/conversations/{conv_id} 读取其中一个对话的历史记录，请使用代表该员工的 OAuth 令牌调用 API。该令牌只能看到这位员工自己的对话；其他任何对话都返回 404，错误码为 conversations.not_found。
只有员工才能核实卡片。核实表示有人检查过内容，因此 POST /v1/cards/{card_id}/verification/verify 和 POST /v1/cards/{card_id}/verify 需要会话，或代表有权核实该卡片的员工的 OAuth 令牌。使用组织 API 密钥或 client_credentials 令牌时，这两个接口返回 400，错误码为 cards.verify_user_account_required。常规检查在此之前进行：密钥看不到的卡片返回 404，无权核实该卡片的密钥返回 403。