API 鉴权
AIS 的平台密钥、应用凭据、渠道平台 Token 和租户用户契约 Token 对应不同身份。请按目标接口选择凭据。
| 凭据 | 请求头 | 用途 |
|---|---|---|
平台 API Key，tk-... | Authorization: Bearer tk-... | 知识管理、检索、标准 Chat、模型列表、访客注册、会话查询等已授权接口 |
应用 AccessToken，ak_... | Authorization: Bearer ak_... | 应用级对话及保留的应用兼容能力 |
| 渠道平台 Token | token: {platformToken} | 开户、查询租户、延期、充值 |
| 租户用户契约 Token | Authorization: Bearer ais-channel-user:{密文} | 已开通契约接入的渠道，以租户管理员或指定用户身份调用业务接口 |
按目标选择凭据
- 已有租户，要调用知识、访客、会话或标准 Chat：使用平台 API Key。
- 要使用一个已配置应用的 Prompt、模型和知识范围：使用该应用 AccessToken 调用应用对话。
- 要创建、查询、延期或充值客户租户：先获取渠道平台 Token。
- 要代表目标租户管理员或指定用户操作：在已开通协议的前提下使用租户用户契约。
- 要让用户进入 AIS 页面：使用契约的登录兑换流程；登录 Token 不作为渠道平台 Token 使用。
不存在“一种 Token 调所有接口”的接入方式。不要根据接口路径含 user、kb 或 openapi 自行推断凭据，始终以对应接口页为准。
平台 API Key
由租户在开放平台密钥管理中创建并配置权限。密钥关联其所属租户和创建用户；无需通过请求体传入 tenantId。服务端会检查密钥有效性、接口模块权限，并按具体业务检查知识库和用户权限。
curl --get "${BASE_URL}/openapi/paas/v1/user/queryByCode" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Accept-Language: zh-CN" \
--data-urlencode "code=partner_visitor_10001"
常用模块权限如下。READ 接口允许 READ 或 WRITE，写接口要求 WRITE；只读模块应配置 READ。
| 接口能力 | 模块编码 | 权限 |
|---|---|---|
| 标准对话 | chat_v1 | READ |
| 知识检索、元数据字段发现 | knowledge_search | READ |
| 知识库列表、详情 / 创建、修改、删除 | knowledge_container | READ / WRITE |
| 文件查询 / 导入、文本、QA、删除 | knowledge_file | READ / WRITE |
| 文件预览、分片读取、网页预览 / 文件上传预览 | knowledge_preview | READ / WRITE |
| 知识分类查询 / 维护 | knowledge_category | READ / WRITE |
| 访客查询 / 注册 | org_user | READ / WRITE |
| 对话主题、历史、记录 | app_chat_record | READ |
| 应用主题配置 | app_config | READ |
文件精确查询与分片列表 要求平台 API Key，并检查密钥创建人的知识库读取权限。仅有问答权限不足以读取原文；这两个接口不能用渠道契约 Token 或旧应用 Token 替代平台密钥。
平台密钥的调用边界
一次成功请求通常经过：识别平台 Key → 确定租户与创建用户 → 检查接口模块权限 → 按业务校验知识资源访问权限。
| 现象 | 常见原因 | 下一步 |
|---|---|---|
| Key 无效 | 错误环境、前缀/空格错误、密钥失效 | 检查密钥来源和 Authorization 格式 |
| 一个接口可用，另一个不可用 | 模块权限不同或入口要求其他凭据 | 核对本页模块表和接口专属要求 |
| 接口有权限但知识库不可读 | Key 创建人缺少资源访问权限 | 由管理员补齐目标资源权限 |
| 可以问答但不能下载/读分片 | ASK_ONLY 与原文读取权限不同 | 不绕过原文权限，按业务需要授权 |
平台 Key 不通过渠道 getToken 接口刷新。密钥的管理与轮换在租户开放平台中完成；不要将它改造成短时平台 Token 的缓存逻辑。
应用凭据
从对应应用获取 AccessToken。应用对话兼容接口 会继续校验应用凭据，并使用应用配置的知识库和 Prompt；它与使用租户配置的 标准 Chat 是不同入口。
旧示例中的 ak_ 不应被视为全部管理接口通用凭据。新接入的访客注册、文件精确查询等按各自页面使用平台 API Key。
渠道凭据
渠道 Token 包括普通 appid/secret 换取方式，以及已开通特殊渠道的短时签名 V2 方式。换取结果放在 token 请求头中。
租户用户契约 由渠道服务端使用双方交换的 AES 密钥生成；省略 userCode 表示租户超级管理员，传入时表示该租户内的指定用户。该凭据不自动创建用户，也不替代业务角色和知识访问授权。
四类凭据的生命周期
| 凭据 | 创建/获取 | 使用时长与更新 | 保管范围 |
|---|---|---|---|
| 平台 API Key | 租户密钥管理 | 按密钥有效配置与管理策略轮换 | 对接服务端 |
| 应用 AccessToken | 对应应用配置 | 按应用凭据策略维护 | 对接服务端，不公开分发 |
| 渠道平台 Token | appid/secret 或 V2 签名换取 | 按返回有效期缓存，处理提前失效 | 渠道服务端 |
| 租户用户契约 | 渠道 AES-GCM 本地签发 | 短时 expireAt，每次签发使用新随机 IV | 服务端；页面接入只交付所需短时结果 |
公共请求头与凭据保存
JSON 写请求使用 Content-Type: application/json；上传文件使用 multipart/form-data，由客户端生成 boundary。可使用 Accept-Language: zh-CN、zh-TW、en、vi 选择提示语言，客户端应按状态码处理结果，不匹配固定提示文案。
平台 API Key、应用 AccessToken 和渠道共享密钥保存在对接服务端。通过 HTTPS 访问，避免把凭据写入页面、客户端源码和日志。只有 登录兑换接口 明确定义了 secureKey 查询参数，应按该接口的编码和保密要求处理。