鉴权与凭证

知办AI 租户开放 API 使用 HTTP Bearer Token 鉴权。所有请求都必须在 Authorization 头里带凭证。

Runtime 换令牌字段统一使用 agent_id / account_id，响应使用 session_token_id；旧字段已在开发期直接删除，详见 API 资源标识字段切换通知。

按你的场景直跳

业务系统长期取数 → API Key 接入
租户自建 Agent 服务运行时取数 → Runtime Access Token 接入
错误响应处理 → 错误码处理
不写代码试一下 → API 在线调试

鉴权流程总览

text

外部业务系统 / 接入方 Agent 服务
        │
        │ Authorization: Bearer <token>
        ▼
知办AI 网关 (zhiban.*.corp)
        │
        ├─ 凭证有效且 scope 足够 → 调用 /api/external/v1/* 并返回数据
        └─ 凭证无效或 scope 不足 → 返回 401 / 403

两种租户凭证对比

维度	API Key	Session Token
前缀	`ek_`	`st_`
颁发方式	租户后台手工创建（一次性返回明文）	Agent / Runtime 用 `client_id + secret` 换取
有效期	长期（默认永久 / 可设过期）	≤60 分钟，按 `expires_in` 缓存，到期或 401 后再换
谁来用	租户外部业务系统（CRM、BI、ETL、Webhook 等）	租户自建 Agent 服务
撤销方式	租户后台一键撤销	撤销母凭证（client_id + secret）即失效
适合场景	「一次配置长期用」	「对话运行时短期、可收窄、可审计地取本租户数据」

一、API Key 接入

最常见的场景：你公司内部某个系统（如 CRM、BI 报表、ETL 数据同步任务）想读知办AI 的知识库数据，给它发一把 API Key 即可。

申请

到知办AI 后台：

左侧菜单 → 凭证与接入 → API Key 管理 → + 新建 Key

填名称（备注用）、勾选权限范围、可设过期时间，确认后弹一次性密钥，仅当时显示一次，立即复制保管。

详细操作见 API Key 管理（租户管理员手册）。

使用

把 API Key 放到调用方的环境变量或密钥库里，每次请求带在头里：

curlPythonGo

bash

curl -H "Authorization: Bearer ek_a1b2c3d4_QwErTyUiOpAsDfGhJkLzXcVbNm123456" \
  https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/documents

python

import os, httpx

API_KEY = os.environ["ZHIBAN_API_KEY"]
r = httpx.get(
    "https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/documents",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(r.json())

req, _ := http.NewRequest("GET",
    "https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/documents", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("ZHIBAN_API_KEY"))
resp, _ := http.DefaultClient.Do(req)

权限范围（scope）

每把 API Key 创建时勾选若干权限范围，调用方仅能调用对应范围的接口：

范围	含义
`tenant.kb.read`	知识库读取
`tenant.kb.write`	知识库写入
`tenant.kb.admin`	知识库管理员
`tenant.kb.list_user_private`	跨用户私有 KB（仅元信息）
`tenant.kb.read_user_private`	跨用户私有 KB（含内容）
`tenant.memory.read`	记忆召回
`tenant.memory.write`	记忆写入
`drive.read`	云盘读取
`tenant.org.read`	组织与人员读取
`tenant.org.write`	组织与人员写入
`tenant.org.admin`	组织与人员管理员
`tenant.auth.introspect`	用户登录 token 解码与有效性检查
`tenant.notification.write`	发送知办数字员工对话通知
`tenant.chat.message.write`	按 EMP 标准主动发送数字员工聊天消息

按最小权限原则勾选，调用接口超出范围会返回 403 scope_denied。

二、Session Token（Agent SDK）接入

适合接入方 Agent 服务 在处理知办AI数字员工会话时实时拉取本租户知识库 / 云盘 / 组织读取数据。流程：

[1] 租户后台拿到 client_id + client_secret  (长期持有)
        │
        ▼
[2] 按会话 / 用户 / 能力上下文换 Session Token
        POST /api/external/v1/oauth/token
        body: { grant_type, client_id, client_secret }
        response: { access_token, token_type, expires_in, scope }
        ▼
[3] 拿到的 access_token (≤60min) 当 Bearer 调业务接口
        Authorization: Bearer st_a1b2c3d4_...
        ▼
[4] SDK 按 expires_in 缓存; 到期前刷新, 或收到 401 后重新换发再重试一次

申请

左侧菜单 → 凭证与接入 → Agent SDK 凭证 → + 接入新 Agent

填名称 + 勾选可借能力（知识库 / 云盘 / 组织与人员读取等），确认后弹一次性显示 client_id + client_secret。

详细操作见 Agent SDK 凭证（租户管理员手册）。

使用

curlPython (SDK)

bash

# 1. 为当前租户/Runtime 换 Session Token
TOKEN=$(curl -sX POST -H "Content-Type: application/json" \
  -d '{"grant_type":"runtime_access","client_id":"'$CLIENT_ID'","client_secret":"'$CLIENT_SECRET'","tenant_id":"'$TENANT_ID'"}' \
  https://zhiban.creditease.corp/api/external/v1/oauth/token | jq -r .access_token)

# 2. 用 Session Token 调业务接口
curl -H "Authorization: Bearer $TOKEN" \
  https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/documents

python

import os

from zhiban_agent_sdk import ZhibanClient

# Runtime 换发时确定租户；知识库请求再传当前数字员工。SDK 内部缓存并自动续期。
client = ZhibanClient.for_runtime_access(
    os.environ["ZHIBAN_BASE_URL"],
    os.environ["ZHIBAN_CLIENT_ID"],
    os.environ["ZHIBAN_CLIENT_SECRET"],
    tenant_id=os.environ["ZHIBAN_TENANT_ID"],
)
result = client.kb.retrieve_associated(
    agent_id=os.environ["ZHIBAN_AGENT_ID"],
    query="公司的年假规则是什么？",
)

知识库的 `agent_id` 在哪里传

不在换发请求里传

grant_type=runtime_access 仍只按当前 Runtime/租户换 st_。知识库的 agent_id 是检索业务参数，不是通用鉴权参数。

调用 POST /api/external/v1/knowledge/retrieve 时，body 必须传当前数字员工的稳定 UUID。服务端校验该数字员工属于 token 租户、状态为已发布并绑定 token Runtime，只检索后台为它关联的知识库。

既有 A2A Agent-bound token 仍使用专用 agent_id 扩展，不因知识库接口调整而改名或改变鉴权逻辑。

普通非 Agent 的机器集成如果使用 grant_type=client_credentials，不传 agent_id；但这种 Token 没有 Agent 上下文，不能调用按数字员工关联知识库检索接口。

换发请求字段（grant_type=runtime_access）：

字段	必填	类型	说明
`grant_type`	是	string	Agent Runtime 固定传 `runtime_access`。
`client_id`	是	string	Agent SDK 凭证的 client_id。
`client_secret`	是	string	Agent SDK 凭证的明文 secret，只在创建时显示一次。
`tenant_id`	是	string	当前租户 ID/UUID；租户级凭证只能选择自身租户。
`agent_id`	否	string	A2A 固定调用方绑定；普通通知、知识库、记忆调用不传。
`account_id`	否	string	当前用户账号 UUID；访问个人私有知识时传入。
`ttl_seconds`	否	number	期望有效期；服务端会按上限收敛，未传使用默认值。

成功响应字段：

字段	类型	说明
`access_token`	string	短期 Session Token，前缀为 `st_`。
`token_type`	string	固定为 `Bearer`。
`expires_in`	number	剩余有效秒数；SDK 按该值缓存，到期前刷新。
`scope`	string	token 能调用的能力范围。
`session_token_id`	string	短期 token 记录 UUID，用于排查和审计。
`bound_agent_id`	string	传入 `agent_id` 且绑定成功时返回。
`bound_account_id`	string	传入 `account_id` 且绑定成功时返回。

SDK 内部：起 client 或首次需要能力时调 /oauth/token 换 Session Token，缓存到过期前 60 秒。每次调业务接口前检查；收到 401 自动续 1 次再重试。 /oauth/token 是 OAuth2 协议端点，成功响应不使用业务 API 的 {success, data} 信封；access_token 位于响应顶层。 Runtime client 默认按 tenant_id 缓存；传了 account_id 时再加入账号维度。A2A 的既有 agent_id 绑定由 A2A 客户端单独处理。

错误码处理

HTTP	错误 code	含义	排查
400	`invalid_request`	`runtime_access` 缺少 `tenant_id`，或知识库业务请求缺少必填 `agent_id`	按对应接口表补齐参数；知识库字段固定使用 snake_case `agent_id`
401	`invalid_api_key`	API Key 不存在 / 被撤销 / 已过期	后台对照 Key 状态
401	`invalid_session_token`	Session Token 不存在 / 过期	重新调 `/oauth/token` 换一份
401	`invalid_client_credentials`	client_id 或 client_secret 错 / 凭证已撤销	后台对照凭证状态
403	`scope_denied`	凭证可借范围不包含目标接口需要的范围	后台改 Key 的 scope 或换一把范围更广的
404	`not_found`	资源不存在 / 跨租户 / 私有不可见	检查 UUID 是否在本租户、是否有访问权
429	`rate_limited`	触发限流	退避重试；高频场景联系运维提配额

401 错误不暴露具体原因（防爆破），均统一返回 "invalid api key" / "invalid session token"。需要本地排查时对照后台凭证状态。

安全注意事项

凭证只能在创建时看到一次——错过只能新建一把；系统只存哈希，不可恢复明文。
放到环境变量或密钥库（Vault / KMS），不要提交到 Git。
给每个调用方独立凭证——出事好定位，撤销面也可控。
定期轮换长期凭证（建议每 90 天一次）。
怀疑泄漏立即撤销 + 新建，不要试图"换哈希"——没这种概念。
生产环境用 HTTPS——HTTP 仅限本地测试。

鉴权与凭证 ​

鉴权流程总览 ​

两种租户凭证对比 ​

一、API Key 接入 ​

申请 ​

使用 ​

权限范围（scope） ​

二、Session Token（Agent SDK）接入 ​

申请 ​

使用 ​

知识库的 agent_id 在哪里传 ​

错误码处理 ​

安全注意事项 ​

相关链接 ​