免登Token第三方接入文档

1. 文档信息

本文档为免登 Token 第三方接入的正式接口说明，覆盖免登凭证的签发、吊销两个接口与完整接入链路；token 校验与免登由嵌入页加载时自动完成，第三方无需对接。

1.1 版本说明

1.2 文档约定

• 请求与响应正文均为 JSON 格式，编码统一使用 UTF-8。
• 时间格式统一为 YYYY-MM-DD HH:mm:ss，时区为东八区。
• 文中「第三方系统」指接入我方 AI 助手能力的业务方系统；「我方」指 maiya AI 平台。
• 接口路径均为相对路径，需拼接网关域名后调用。

2. 概述

介绍文档目的、适用读者与核心术语，帮助第三方开发者在阅读接口细节前建立整体认知。

2.1 文档目的与适用读者

文档目的

本文档面向第三方系统开发者，说明如何通过免登 Token 机制将 maiya AI 助手嵌入第三方系统：

1. 第三方系统后端为其用户签发自包含身份的免登 token（接入配置 + 用户信息）。
2. token 通过 URL 携带至我方嵌入页面，我方验签后为该用户免登录建立会话。
3. 会话建立后即可直接创建需求（对话），全程无需第三方用户在我方系统注册或登录。

适用读者

2.2 术语表

3. 接入总览

免登接入对外提供两个接口：签发与吊销；token 校验与免登会话建立由嵌入页加载时自动完成，第三方无需对接。本章给出接口一览与相关系统角色划分。

3.1 接口一览

3.2 相关系统角色

免登链路涉及三个角色：

角色协作主线：第三方系统签发并投递 token → 嵌入页自动校验 token 免登 → 用户在嵌入页对话 → 我方后台执行并经 WebSocket 推送结果。

4. 接入前置条件

第三方接入前需完成接入配置开通、持有 third_party_id，并满足网络与环境要求。当前为简化接入期，暂不校验 access_key 与请求签名。

4.1 接入要求与环境说明

开通要求

1. 已由我方完成接入配置开通（ai_assistant_access 记录创建且 status=1、is_valid=1），并绑定了目标 AI 助手与模型。
2. 第三方系统持有我方发放的 third_party_id（接入标志）。
3. 第三方后端可访问我方接口网关域名，嵌入页面可访问我方前端资源与 WebSocket 服务。

网络与环境

• 接口调用：HTTP/HTTPS，请求与响应均为 JSON（UTF-8）。
• WebSocket 消息通道：ws://host:9099/ws，由嵌入页自动建立连接，需保证嵌入页运行环境可访问该端口。
• 嵌入方式：iframe（<iframe src="https://xxx/embed?access_token=xxx">）或 window.open 新窗口。

当前简化期说明

• 当前为简化接入期：签发接口暂不校验 access_key 与请求签名，仅凭 third_party_id 定位接入配置即可签发。
• 后续将启用 HMAC-SHA256 请求签名校验（配合 ai_assistant_access_key 密钥表），启用前我方会提前通知第三方，届时需按通知补充签名逻辑。
• 签名启用后，免登 token 的验签密钥也将切换为按接入配置分发，替换当前的系统固定密钥。

5. 接口一：签发免登 Token（issue）

第三方系统后端调用本接口，为自己的用户签发免登 token。token 自包含身份（接入配置 + 用户），可通过 URL 携带传递给嵌入页面。

5.1 功能说明

第三方系统后端调用本接口，为自己的用户签发免登 token。第三方只需传入 third_party_id（接入标志）+ 用户信息，系统据此查出 assistant_access_id 并生成自包含 token。签发后落库 ai_assistant_access_token 一条记录，status=1。

简化说明：当前暂不校验 access_key/签名，仅凭 third_party_id 定位接入配置即可签发。后续接入签名算法（HMAC-SHA256 + ai_assistant_access_key）后再加验证。

• 接口地址：POST /assistant/access/token/issue
• 请求方式：POST（JSON）

5.2 请求参数

biz_vars 卡片展示固定字段

以上字段建议始终传入。biz_vars 同时支持任意扩展字段（如 level、member_id），均原样快照存储。

示例：

{
  "card_title": "产品设计专家",
  "card_description": "专业的产品设计助手",
  "card_logo_url": "https://...",
  "card_price": "99",
  "card_unit": "元/月",
  "level": "VIP",
  "member_id": "M001"
}

5.3 返回参数

data.extra 结构

data.extra 落库于 ai_assistant_access_token.extra，包含两部分：

5.4 请求示例

{
  "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"
  }
}

5.5 返回示例

{
  "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..."
  }
}

5.6 签发逻辑说明

Step 1 — 通过 third_party_id 定位接入配置

• 查 ai_assistant_access where third_party_id + is_valid=1 + status=1
• 得到 id（即 assistant_access_id）、assistant_id、other_config、access_mode
• 不存在或已停用 → 返回 400「接入标志不存在或已停用」

Step 2 — 组装 payload 并签名

payload = {
  assistant_access_id,   # 内部计算得到（Step 1），第三方不感知

biz_user_id, # 外接方用户ID → 免登身份

  display_name,          # 展示名
  iat,                   # 签发时间戳
  exp                    # 失效时间戳（= 签发时间 + 24h）
}
token = base64url(payload) + "." + HMAC-SHA256(secret_key, base64url(payload))

当前 secret_key 暂用系统固定密钥；后续接入 ai_assistant_access_key 后改为按接入配置取密钥验签。

Step 3 — 组装 extra 快照

• biz_vars：请求传入什么就存什么，原样快照，不做 default 补全
• sys_vars：自动填充 channel（third_party_id）、access_mode、issued_at

Step 4 — 落库 ai_assistant_access_token

• 写入：token + assistant_access_id（Step 1 得到）+ biz_user_id + display_name + extra(JSON) + status=1 + valid_from(now) + valid_to(now + 24h)

Step 5 — 创建/更新外接用户 embed_external_user

• 按 (assistant_access_id, biz_user_id) 查 embed_external_user，不存在则创建
• 更新 display_name、last_active_time

关键字段映射：第三方只持有 third_party_id（接入标志），assistant_access_id 是系统内部通过 third_party_id 查 ai_assistant_access 计算得到的，不会暴露给第三方。

6. 接口二：吊销 Token（revoke）

吊销指定 token（置 status=0），即时生效。第三方系统用户登出或安全策略触发时调用。

6.1 功能说明

吊销指定 token（置 status=0），即时生效。第三方系统用户登出或安全策略触发时调用。

• 接口地址：POST /assistant/access/token/revoke
• 请求方式：POST（JSON）

6.2 请求参数

6.3 返回参数

6.4 请求示例

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJhA..."
}

6.5 返回示例

{
  "code": 200,
  "message": "Token 已吊销",
  "data": {
    "token_id": 101
  }
}

6.6 说明

• 置 ai_assistant_access_token.status=0，即时生效。
• 已吊销的 token 即时失效，嵌入页免登校验不通过，无法再用于免登。
• 建议定时任务把 valid_to < now 的记录也置 status=0。

7. 免登链路全流程

以分步编号列表描述从第三方用户已登录到收到 AI 回复的完整免登链路。

7.1 全流程分步说明

本图从第三方接入视角描述接入全流程，仅展示第三方需要参与的步骤。

图 1 流程图

分步说明（第三方动作视角）：

以上为第三方视角概览；完整交互时序与内部处理细节见平台内部文档。

8. 错误码与异常处理

汇总各接口的错误码、触发场景与第三方系统的处理建议。

8.1 错误码一览与处理建议

通用处理建议：

1. 400 属配置类错误，重试无效，需先排查 third_party_id 配置。
2. 签发接口建议做失败告警，持续 400 通常意味着接入配置变更。
3. token 过期或被吊销时，嵌入页免登失败并向用户展示错误提示；第三方可引导用户从自身系统重新进入（自动触发重新签发），必要时排查是否误调 revoke。

9. 安全与最佳实践

token 有效期、URL 携带注意事项、登出吊销、传输安全、biz_vars 快照语义等安全实践要求。

9.1 安全要求与最佳实践

1. token 有效期管理

• token 默认有效期 24 小时（valid_to = 签发时间 + 24h），过期后无法用于免登。
• 建议「按需签发」：用户进入嵌入页时实时签发，不要提前批量签发囤积。
• 不缓存已过期的 token；每次进入嵌入页重新走签发流程成本极低，且更安全。

2. URL 携带注意事项

• token 通过 URL 参数携带（embed_url 或自行拼接），需做 URL 安全编码，避免特殊字符截断。
• token 可能出现在浏览器历史、服务器访问日志中，因此有效期限制是必要防线，禁止放大有效期长期复用。
• iframe 嵌入时建议配置合适的 CSP 与 referrer 策略，减少 token 泄漏面。

3. 登出即吊销

• 第三方系统用户登出时，应调用 revoke 接口吊销该用户的免登 token，防止登出后嵌入页仍可访问。
• 安全事件（怀疑 token 泄漏）时也应立即吊销。

4. 传输安全

• 生产环境强制使用 HTTPS 调用签发/吊销接口，禁止明文 HTTP 传输 token。
• WebSocket 生产环境建议使用 wss。

5. biz_vars 快照语义

• biz_vars 在签发时原样快照落库（extra.biz_vars），不做 default 补全；之后第三方修改业务数据不会影响已签发 token 内的快照。
• 业务数据变化需要反映到嵌入页时，应重新签发新 token。
• 卡片展示固定字段（card_title、card_description、card_logo_url、card_price、card_unit）建议每次签发都传入完整值。

6. 签名机制演进（提前准备）

• 当前简化期暂不校验 access_key/签名；后续启用 HMAC-SHA256 请求签名（配合 ai_assistant_access_key）。
• 密钥管理届时由我方分发，请勿将密钥硬编码到前端或提交到代码仓库。