智能体外放对接指南
免登Token第三方接入指南
免登 Token 第三方接入的正式接口说明，覆盖免登凭证的签发、吊销两个接口与完整接入链路。
最近更新：2026.08.31 17:12
<style>table{border-collapse:collapse;width:100%;margin:8px 0;font-size:14px}th,td{border:1px solid #d0d0d0;padding:6px 10px;text-align:left;vertical-align:top}thead th{background:#f0f0f0;font-weight:700}pre{background:#f6f8fa;padding:10px 14px;border-radius:6px;overflow-x:auto;font-size:13px;line-height:1.5}pre code{font-family:Consolas,Menlo,monospace;white-space:pre-wrap;word-break:break-all;background:none;padding:0}code{font-family:Consolas,Menlo,monospace;background:#f6f8fa;padding:1px 4px;border-radius:3px;font-size:13px}blockquote{margin:8px 0;padding:6px 14px;border-left:4px solid #e0e0e0;color:#555;background:#fafafa}</style><h1>免登Token第三方接入文档</h1><h2>1. 文档信息</h2><p>本文档为免登 Token 第三方接入的正式接口说明，覆盖免登凭证的签发、吊销两个接口与完整接入链路；token 校验与免登由嵌入页加载时自动完成，第三方无需对接。</p><h3>1.1 版本说明</h3><table><thead><tr><th><strong>版本</strong></th><th><strong>日期</strong></th><th><strong>说明</strong></th><th><strong>作者</strong></th></tr></thead><tbody><tr><td>v1.0.0</td><td>2026-08-25</td><td>首次发布：签发、校验、吊销三个接口与免登链路全流程</td><td>maiya AI 平台</td></tr><tr><td>v1.1.0</td><td>2026-08-25</td><td>8.1 全流程分步说明改为 mermaid 流程图呈现，附节点对照表</td><td>maiya AI 平台</td></tr><tr><td>v1.2.0</td><td>2026-08-25</td><td>8.1/8.2 简化为第三方视角：流程图精简至 8 节点，移除内部表与内部流程细节</td><td>maiya AI 平台</td></tr><tr><td>v1.3.0</td><td>2026-08-25</td><td>删除接口二（verify）章节：该接口由嵌入页内部自动调用，第三方无需对接；后续章节重编号</td><td>maiya AI 平台</td></tr></tbody></table><h3>1.2 文档约定</h3><ul><li>请求与响应正文均为 JSON 格式，编码统一使用 UTF-8。</li><li>时间格式统一为 <code>YYYY-MM-DD HH:mm:ss</code>，时区为东八区。</li><li>文中「第三方系统」指接入我方 AI 助手能力的业务方系统；「我方」指 maiya AI 平台。</li><li>接口路径均为相对路径，需拼接网关域名后调用。</li></ul><h2>2. 概述</h2><p>介绍文档目的、适用读者与核心术语，帮助第三方开发者在阅读接口细节前建立整体认知。</p><h3>2.1 文档目的与适用读者</h3><p><strong>文档目的</strong></p><p>本文档面向第三方系统开发者，说明如何通过免登 Token 机制将 maiya AI 助手嵌入第三方系统：</p><ol start="1"><li>第三方系统后端为其用户签发自包含身份的免登 token（接入配置 + 用户信息）。</li><li>token 通过 URL 携带至我方嵌入页面，我方验签后为该用户免登录建立会话。</li><li>会话建立后即可直接创建需求（对话），全程无需第三方用户在我方系统注册或登录。</li></ol><p><strong>适用读者</strong></p><table><thead><tr><th><strong>读者</strong></th><th><strong>关注内容</strong></th></tr></thead><tbody><tr><td>第三方系统后端开发者</td><td>第 5 章签发接口、第 6 章吊销接口、第 8 章错误处理</td></tr><tr><td>第三方系统前端 / 嵌入页开发者</td><td>第 7 章免登链路全流程、第 9 章安全实践</td></tr><tr><td>API 消费方 / 集成方</td><td>第 3 章接入总览、第 4 章前置条件</td></tr></tbody></table><h3>2.2 术语表</h3><table><thead><tr><th><strong>术语</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>third_party_id</td><td>接入标志，第三方系统持有的唯一接入标识，如 agent-maiya-prod-design-9f3a2c8d，由我方开通接入配置后发放</td></tr><tr><td>assistant_access_id</td><td>接入配置内部 ID，系统通过 third_party_id 查询得到，不暴露给第三方</td></tr><tr><td>biz_user_id</td><td>外接方用户 ID，第三方系统内用户的唯一标识</td></tr><tr><td>display_name</td><td>展示名（昵称/姓名），免登后直接渲染，不传则使用 biz_user_id</td></tr><tr><td>token</td><td>免登 token，自包含身份（接入配置 + 用户），URL 安全 base64 + HMAC 签名，通过 URL 携带</td></tr><tr><td>biz_vars</td><td>业务变量实际值（key-value），接入方传入，原样快照存储，不做默认值补全</td></tr><tr><td>sys_vars</td><td>系统变量，签发时自动填充 channel、access_mode、issued_at</td></tr><tr><td>embed_url</td><td>拼接好的嵌入 URL（page 模式可直接使用），形如 https://embed.maiya.ai/agents/{third_party_id}?token={token}</td></tr></tbody></table><h2>3. 接入总览</h2><p>免登接入对外提供两个接口：签发与吊销；token 校验与免登会话建立由嵌入页加载时自动完成，第三方无需对接。本章给出接口一览与相关系统角色划分。</p><h3>3.1 接口一览</h3><table><thead><tr><th><strong>编号</strong></th><th><strong>接口名称</strong></th><th><strong>方法</strong></th><th><strong>路径</strong></th><th><strong>用途</strong></th></tr></thead><tbody><tr><td>1</td><td>签发免登 Token</td><td>POST</td><td>/assistant/access/token/issue</td><td>第三方后端为其用户签发免登 token</td></tr><tr><td>2</td><td>吊销 Token</td><td>POST</td><td>/assistant/access/token/revoke</td><td>吊销指定 token，即时生效</td></tr></tbody></table><h3>3.2 相关系统角色</h3><p>免登链路涉及三个角色：</p><table><thead><tr><th><strong>角色</strong></th><th><strong>职责</strong></th></tr></thead><tbody><tr><td>第三方系统</td><td>业务方系统。后端调用签发接口获取 token 与 embed_url，将 token 拼入嵌入 URL；用户登出或安全策略触发时调用吊销接口</td></tr><tr><td>我方后台</td><td>生成免登 token 并在用户进入嵌入页时自动校验，维护接入配置（ai_assistant_access）、免登 token（ai_assistant_access_token）、外接用户（embed_external_user）、系统登录凭证（comm_user / comm_token）与项目会话（project_session）</td></tr><tr><td>我方前端（嵌入页面）</td><td>加载时自动从 URL 取 token 完成校验与免登，初始化聊天界面，建立 WebSocket 连接，承载用户对话</td></tr></tbody></table><p>角色协作主线：第三方系统签发并投递 token → 嵌入页自动校验 token 免登 → 用户在嵌入页对话 → 我方后台执行并经 WebSocket 推送结果。</p><h2>4. 接入前置条件</h2><p>第三方接入前需完成接入配置开通、持有 third_party_id，并满足网络与环境要求。当前为简化接入期，暂不校验 access_key 与请求签名。</p><h3>4.1 接入要求与环境说明</h3><p><strong>开通要求</strong></p><ol start="1"><li>已由我方完成接入配置开通（ai_assistant_access 记录创建且 status=1、is_valid=1），并绑定了目标 AI 助手与模型。</li><li>第三方系统持有我方发放的 third_party_id（接入标志）。</li><li>第三方后端可访问我方接口网关域名，嵌入页面可访问我方前端资源与 WebSocket 服务。</li></ol><p><strong>网络与环境</strong></p><ul><li>接口调用：HTTP/HTTPS，请求与响应均为 JSON（UTF-8）。</li><li>WebSocket 消息通道：<code>ws://host:9099/ws</code>，由嵌入页自动建立连接，需保证嵌入页运行环境可访问该端口。</li><li>嵌入方式：iframe（<code><iframe src="https://xxx/embed?access_token=xxx"></code>）或 window.open 新窗口。</li></ul><p><strong>当前简化期说明</strong></p><ul><li>当前为简化接入期：签发接口暂不校验 access_key 与请求签名，仅凭 third_party_id 定位接入配置即可签发。</li><li>后续将启用 HMAC-SHA256 请求签名校验（配合 ai_assistant_access_key 密钥表），启用前我方会提前通知第三方，届时需按通知补充签名逻辑。</li><li>签名启用后，免登 token 的验签密钥也将切换为按接入配置分发，替换当前的系统固定密钥。</li></ul><h2>5. 接口一：签发免登 Token（issue）</h2><p>第三方系统后端调用本接口，为自己的用户签发免登 token。token 自包含身份（接入配置 + 用户），可通过 URL 携带传递给嵌入页面。</p><h3>5.1 功能说明</h3><p>第三方系统后端调用本接口，为自己的用户签发免登 token。第三方只需传入 <code>third_party_id</code>（接入标志）+ 用户信息，系统据此查出 <code>assistant_access_id</code> 并生成自包含 token。签发后落库 <code>ai_assistant_access_token</code> 一条记录，<code>status=1</code>。</p><p><strong>简化说明</strong>：当前暂不校验 <code>access_key</code>/签名，仅凭 <code>third_party_id</code> 定位接入配置即可签发。后续接入签名算法（HMAC-SHA256 + <code>ai_assistant_access_key</code>）后再加验证。</p><ul><li><strong>接口地址</strong>：<code>POST /assistant/access/token/issue</code></li><li><strong>请求方式</strong>：POST（JSON）</li></ul><h3>5.2 请求参数</h3><table><thead><tr><th><strong>参数名</strong></th><th><strong>类型</strong></th><th><strong>必填</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>third_party_id</td><td>string</td><td>是</td><td>接入标志（第三方持有的，如 agent-maiya-prod-design-9f3a2c8d）</td></tr><tr><td>biz_user_id</td><td>string</td><td>是</td><td>外接方用户 ID（第三方系统用户唯一标识）</td></tr><tr><td>display_name</td><td>string</td><td>否</td><td>展示名（昵称/姓名），免登后直接渲染，不传则用 biz_user_id</td></tr><tr><td>biz_vars</td><td>object</td><td>否</td><td>业务变量实际值（key-value），传入什么就存什么，不做 default 补全。卡片展示固定字段见下表</td></tr></tbody></table><p><strong>biz_vars 卡片展示固定字段</strong></p><table><thead><tr><th><strong>字段名</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>card_title</td><td>卡片名称</td></tr><tr><td>card_description</td><td>卡片描述</td></tr><tr><td>card_logo_url</td><td>卡片 Logo URL</td></tr><tr><td>card_price</td><td>卡片价格</td></tr><tr><td>card_unit</td><td>卡片单位</td></tr></tbody></table><p>以上字段建议始终传入。biz_vars 同时支持任意扩展字段（如 level、member_id），均原样快照存储。</p><p>示例：</p><pre><code>{
"card_title": "产品设计专家",
"card_description": "专业的产品设计助手",
"card_logo_url": "https://...",
"card_price": "99",
"card_unit": "元/月",
"level": "VIP",
"member_id": "M001"
}</code></pre><h3>5.3 返回参数</h3><table><thead><tr><th><strong>参数名</strong></th><th><strong>类型</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>code</td><td>integer</td><td>200 成功；400 = third_party_id 不存在/已停用</td></tr><tr><td>message</td><td>string</td><td>响应消息</td></tr><tr><td>data.token</td><td>string</td><td>免登 token（URL 安全 base64 + HMAC 签名，URL 携带）</td></tr><tr><td>data.token_id</td><td>integer</td><td>token 记录 ID（ai_assistant_access_token.id）</td></tr><tr><td>data.biz_user_id</td><td>string</td><td>外接方用户 ID</td></tr><tr><td>data.display_name</td><td>string</td><td>展示名</td></tr><tr><td>data.extra</td><td>object</td><td>额外变量快照（业务变量实际值 + 系统变量自动填充）</td></tr><tr><td>data.valid_from</td><td>string</td><td>生效时间 YYYY-MM-DD HH:mm:ss</td></tr><tr><td>data.valid_to</td><td>string</td><td>失效时间 YYYY-MM-DD HH:mm:ss（默认 = 签发时间 + 24h）</td></tr><tr><td>data.embed_url</td><td>string</td><td>拼接好的嵌入 URL（page 模式可直接使用），如 https://embed.maiya.ai/agents/{third_party_id}?token={token}</td></tr></tbody></table><p><strong>data.extra 结构</strong></p><p>data.extra 落库于 ai_assistant_access_token.extra，包含两部分：</p><table><thead><tr><th><strong>属性</strong></th><th><strong>类型</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>biz_vars</td><td>object</td><td>业务变量实际值快照（接入方传入原值，不做 default 补全），含卡片展示固定字段 card_title、card_description、card_logo_url、card_price、card_unit</td></tr><tr><td>sys_vars</td><td>object</td><td>系统变量自动填充：channel（= third_party_id）、access_mode（接入模式）、issued_at（签发时间）</td></tr></tbody></table><h3>5.4 请求示例</h3><pre><code>{
"third_party_id": "agent-maiya-prod-design-9f3a2c8d",
"biz_user_id": "ext-user-10086",
"display_name": "张三",
"biz_vars": {
"card_title": "产品设计专家",
"card_description": "专业的产品设计助手，提供原型设计、需求分析等服务",
"card_logo_url": "https://metaglobal-static-resource.oss-cn-beijing.aliyuncs.com/maiya/img/icon/ai-4.png",
"card_price": "99",
"card_unit": "元/月",
"level": "VIP",
"member_id": "M001"
}
}</code></pre><h3>5.5 返回示例</h3><pre><code>{
"code": 200,
"message": "Token 签发成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiJ9.eyJhA...（省略）",
"token_id": 101,
"biz_user_id": "ext-user-10086",
"display_name": "张三",
"extra": {
"biz_vars": {
"card_title": "产品设计专家",
"card_description": "专业的产品设计助手，提供原型设计、需求分析等服务",
"card_logo_url": "https://metaglobal-static-resource.oss-cn-beijing.aliyuncs.com/maiya/img/icon/ai-4.png",
"card_price": "99",
"card_unit": "元/月",
"level": "VIP",
"member_id": "M001",
"product_line": "标准版"
},
"sys_vars": {
"channel": "agent-maiya-prod-design-9f3a2c8d",
"access_mode": "page",
"issued_at": "2026-08-03 10:00:00"
}
},
"valid_from": "2026-08-03 10:00:00",
"valid_to": "2026-08-04 10:00:00",
"embed_url": "/customer-service?access_token=eyJhbGciOiJIUzI1NiJ9..."
}
}</code></pre><h3>5.6 签发逻辑说明</h3><p><strong>Step 1 — 通过 third_party_id 定位接入配置</strong></p><ul><li>查 ai_assistant_access where third_party_id + is_valid=1 + status=1</li><li>得到 id（即 assistant_access_id）、assistant_id、other_config、access_mode</li><li>不存在或已停用 → 返回 400「接入标志不存在或已停用」</li></ul><p><strong>Step 2 — 组装 payload 并签名</strong></p><pre><code>payload = {
assistant_access_id, # 内部计算得到（Step 1），第三方不感知</code></pre><p><span style="color:#333333"> biz_user_id, # 外接方用户ID → 免登身份</span></p><pre><code> display_name, # 展示名
iat, # 签发时间戳
exp # 失效时间戳（= 签发时间 + 24h）
}
token = base64url(payload) + "." + HMAC-SHA256(secret_key, base64url(payload))</code></pre><p>当前 secret_key 暂用系统固定密钥；后续接入 ai_assistant_access_key 后改为按接入配置取密钥验签。</p><p><strong>Step 3 — 组装 extra 快照</strong></p><ul><li>biz_vars：请求传入什么就存什么，原样快照，不做 default 补全</li><li>sys_vars：自动填充 channel（third_party_id）、access_mode、issued_at</li></ul><p><strong>Step 4 — 落库 ai_assistant_access_token</strong></p><ul><li>写入：token + assistant_access_id（Step 1 得到）+ biz_user_id + display_name + extra(JSON) + status=1 + valid_from(now) + valid_to(now + 24h)</li></ul><p><strong>Step 5 — 创建/更新外接用户 embed_external_user</strong></p><ul><li>按 (assistant_access_id, biz_user_id) 查 embed_external_user，不存在则创建</li><li>更新 display_name、last_active_time</li></ul><p><strong>关键字段映射</strong>：第三方只持有 third_party_id（接入标志），assistant_access_id 是系统内部通过 third_party_id 查 ai_assistant_access 计算得到的，不会暴露给第三方。</p><h2>6. 接口二：吊销 Token（revoke）</h2><p>吊销指定 token（置 status=0），即时生效。第三方系统用户登出或安全策略触发时调用。</p><h3>6.1 功能说明</h3><p>吊销指定 token（置 status=0），即时生效。第三方系统用户登出或安全策略触发时调用。</p><ul><li><strong>接口地址</strong>：<code>POST /assistant/access/token/revoke</code></li><li><strong>请求方式</strong>：POST（JSON）</li></ul><h3>6.2 请求参数</h3><table><thead><tr><th><strong>参数名</strong></th><th><strong>类型</strong></th><th><strong>必填</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>token</td><td>string</td><td>是</td><td>待吊销的 token</td></tr></tbody></table><h3>6.3 返回参数</h3><table><thead><tr><th><strong>参数名</strong></th><th><strong>类型</strong></th><th><strong>说明</strong></th></tr></thead><tbody><tr><td>code</td><td>integer</td><td>200 成功</td></tr><tr><td>message</td><td>string</td><td>响应消息</td></tr><tr><td>data.token_id</td><td>integer</td><td>已吊销的 token 记录 ID</td></tr></tbody></table><h3>6.4 请求示例</h3><pre><code>{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJhA..."
}</code></pre><h3>6.5 返回示例</h3><pre><code>{
"code": 200,
"message": "Token 已吊销",
"data": {
"token_id": 101
}
}</code></pre><h3>6.6 说明</h3><ul><li>置 ai_assistant_access_token.status=0，即时生效。</li><li>已吊销的 token 即时失效，嵌入页免登校验不通过，无法再用于免登。</li><li>建议定时任务把 valid_to < now 的记录也置 status=0。</li></ul><h2>7. 免登链路全流程</h2><p>以分步编号列表描述从第三方用户已登录到收到 AI 回复的完整免登链路。</p><h3>7.1 全流程分步说明</h3><p>本图从第三方接入视角描述接入全流程，仅展示第三方需要参与的步骤。</p><p><img src="https://myaifast-maiya.oss-cn-beijing.aliyuncs.com/doc%2F5630d767cc32403db25929ccdb2e6ebf.png?OSSAccessKeyId=LTAI5tSppzC6jVomRhsfNeJc&Expires=1791636702&Signature=axcUR7Tm5UAef%2B0IUz08wWtSPo4%3D" data-oss-key="doc/5630d767cc32403db25929ccdb2e6ebf.png"></p><p>图 1 流程图</p><p>分步说明（第三方动作视角）：</p><table><thead><tr><th><strong>步骤</strong></th><th><strong>谁做</strong></th><th><strong>做什么</strong></th><th><strong>用到的接口/数据</strong></th></tr></thead><tbody><tr><td>1. 获取 token</td><td>第三方后端</td><td>调用签发接口，传 third_party_id + biz_user_id + display_name</td><td>POST /assistant/access/token/issue，返回 data.token、data.embed_url</td></tr><tr><td>2. 嵌入页面</td><td>第三方前端</td><td>用返回的 embed_url（或自行拼 token 到嵌入 URL），iframe / window.open 打开</td><td>data.embed_url</td></tr><tr><td>3. 用户进入</td><td>终端用户</td><td>打开嵌入页，平台自动校验 token、初始化聊天界面</td><td>平台自动处理，第三方无感知</td></tr><tr><td>4. 开始对话</td><td>终端用户</td><td>在聊天框发消息，接收 AI 回复</td><td>平台自动处理</td></tr><tr><td>5.（可选）吊销 token</td><td>第三方后端</td><td>用户登出或安全需要时吊销</td><td>POST /assistant/access/token/revoke</td></tr></tbody></table><p>以上为第三方视角概览；完整交互时序与内部处理细节见平台内部文档。</p><h2>8. 错误码与异常处理</h2><p>汇总各接口的错误码、触发场景与第三方系统的处理建议。</p><h3>8.1 错误码一览与处理建议</h3><table><thead><tr><th><strong>错误码</strong></th><th><strong>触发场景</strong></th><th><strong>说明</strong></th><th><strong>第三方处理建议</strong></th></tr></thead><tbody><tr><td>400</td><td>third_party_id 不存在或已停用</td><td>签发时查不到 is_valid=1 且 status=1 的接入配置</td><td>核对 third_party_id 是否正确；确认接入配置是否被停用；联系我方重新开通</td></tr></tbody></table><p><strong>通用处理建议</strong>：</p><ol start="1"><li>400 属配置类错误，重试无效，需先排查 third_party_id 配置。</li><li>签发接口建议做失败告警，持续 400 通常意味着接入配置变更。</li><li>token 过期或被吊销时，嵌入页免登失败并向用户展示错误提示；第三方可引导用户从自身系统重新进入（自动触发重新签发），必要时排查是否误调 revoke。</li></ol><h2>9. 安全与最佳实践</h2><p>token 有效期、URL 携带注意事项、登出吊销、传输安全、biz_vars 快照语义等安全实践要求。</p><h3>9.1 安全要求与最佳实践</h3><p><strong>1. token 有效期管理</strong></p><ul><li>token 默认有效期 24 小时（valid_to = 签发时间 + 24h），过期后无法用于免登。</li><li>建议「按需签发」：用户进入嵌入页时实时签发，不要提前批量签发囤积。</li><li>不缓存已过期的 token；每次进入嵌入页重新走签发流程成本极低，且更安全。</li></ul><p><strong>2. URL 携带注意事项</strong></p><ul><li>token 通过 URL 参数携带（embed_url 或自行拼接），需做 URL 安全编码，避免特殊字符截断。</li><li>token 可能出现在浏览器历史、服务器访问日志中，因此有效期限制是必要防线，禁止放大有效期长期复用。</li><li>iframe 嵌入时建议配置合适的 CSP 与 referrer 策略，减少 token 泄漏面。</li></ul><p><strong>3. 登出即吊销</strong></p><ul><li>第三方系统用户登出时，应调用 revoke 接口吊销该用户的免登 token，防止登出后嵌入页仍可访问。</li><li>安全事件（怀疑 token 泄漏）时也应立即吊销。</li></ul><p><strong>4. 传输安全</strong></p><ul><li>生产环境强制使用 HTTPS 调用签发/吊销接口，禁止明文 HTTP 传输 token。</li><li>WebSocket 生产环境建议使用 wss。</li></ul><p><strong>5. biz_vars 快照语义</strong></p><ul><li>biz_vars 在签发时原样快照落库（extra.biz_vars），不做 default 补全；之后第三方修改业务数据不会影响已签发 token 内的快照。</li><li>业务数据变化需要反映到嵌入页时，应重新签发新 token。</li><li>卡片展示固定字段（card_title、card_description、card_logo_url、card_price、card_unit）建议每次签发都传入完整值。</li></ul><p><strong>6. 签名机制演进（提前准备）</strong></p><ul><li>当前简化期暂不校验 access_key/签名；后续启用 HMAC-SHA256 请求签名（配合 ai_assistant_access_key）。</li><li>密钥管理届时由我方分发，请勿将密钥硬编码到前端或提交到代码仓库。</li></ul>