免登Token第三方接入文档

1. 文档信息

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

1.1 版本说明

版本日期说明作者v1.0.02026-08-25首次发布：签发、校验、吊销三个接口与免登链路全流程maiya AI 平台v1.1.02026-08-258.1 全流程分步说明改为 mermaid 流程图呈现，附节点对照表maiya AI 平台v1.2.02026-08-258.1/8.2 简化为第三方视角：流程图精简至 8 节点，移除内部表与内部流程细节maiya AI 平台v1.3.02026-08-25删除接口二（verify）章节：该接口由嵌入页内部自动调用，第三方无需对接；后续章节重编号maiya AI 平台

1.2 文档约定

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

2. 概述

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

2.1 文档目的与适用读者

文档目的

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

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

适用读者

读者关注内容第三方系统后端开发者第 5 章签发接口、第 6 章吊销接口、第 8 章错误处理第三方系统前端 / 嵌入页开发者第 7 章免登链路全流程、第 9 章安全实践API 消费方 / 集成方第 3 章接入总览、第 4 章前置条件

2.2 术语表

术语说明third_party_id接入标志，第三方系统持有的唯一接入标识，如 agent-maiya-prod-design-9f3a2c8d，由我方开通接入配置后发放assistant_access_id接入配置内部 ID，系统通过 third_party_id 查询得到，不暴露给第三方biz_user_id外接方用户 ID，第三方系统内用户的唯一标识display_name展示名（昵称/姓名），免登后直接渲染，不传则使用 biz_user_idtoken免登 token，自包含身份（接入配置 + 用户），URL 安全 base64 + HMAC 签名，通过 URL 携带biz_vars业务变量实际值（key-value），接入方传入，原样快照存储，不做默认值补全sys_vars系统变量，签发时自动填充 channel、access_mode、issued_atembed_url拼接好的嵌入 URL（page 模式可直接使用），形如 https://embed.maiya.ai/agents/{third_party_id}?token={token}

3. 接入总览

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

3.1 接口一览

编号接口名称方法路径用途1签发免登 TokenPOST/assistant/access/token/issue第三方后端为其用户签发免登 token2吊销 TokenPOST/assistant/access/token/revoke吊销指定 token，即时生效

3.2 相关系统角色

免登链路涉及三个角色：

角色职责第三方系统业务方系统。后端调用签发接口获取 token 与 embed_url，将 token 拼入嵌入 URL；用户登出或安全策略触发时调用吊销接口我方后台生成免登 token 并在用户进入嵌入页时自动校验，维护接入配置（ai_assistant_access）、免登 token（ai_assistant_access_token）、外接用户（embed_external_user）、系统登录凭证（comm_user / comm_token）与项目会话（project_session）我方前端（嵌入页面）加载时自动从 URL 取 token 完成校验与免登，初始化聊天界面，建立 WebSocket 连接，承载用户对话

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

4. 接入前置条件

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

4.1 接入要求与环境说明

开通要求

已由我方完成接入配置开通（ai_assistant_access 记录创建且 status=1、is_valid=1），并绑定了目标 AI 助手与模型。
第三方系统持有我方发放的 third_party_id（接入标志）。
第三方后端可访问我方接口网关域名，嵌入页面可访问我方前端资源与 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 请求参数

参数名类型必填说明third_party_idstring是接入标志（第三方持有的，如 agent-maiya-prod-design-9f3a2c8d）biz_user_idstring是外接方用户 ID（第三方系统用户唯一标识）display_namestring否展示名（昵称/姓名），免登后直接渲染，不传则用 biz_user_idbiz_varsobject否业务变量实际值（key-value），传入什么就存什么，不做 default 补全。卡片展示固定字段见下表

biz_vars 卡片展示固定字段

字段名说明card_title卡片名称card_description卡片描述card_logo_url卡片 Logo URLcard_price卡片价格card_unit卡片单位

以上字段建议始终传入。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 返回参数

参数名类型说明codeinteger200 成功；400 = third_party_id 不存在/已停用messagestring响应消息data.tokenstring免登 token（URL 安全 base64 + HMAC 签名，URL 携带）data.token_idintegertoken 记录 ID（ai_assistant_access_token.id）data.biz_user_idstring外接方用户 IDdata.display_namestring展示名data.extraobject额外变量快照（业务变量实际值 + 系统变量自动填充）data.valid_fromstring生效时间 YYYY-MM-DD HH:mm:ssdata.valid_tostring失效时间 YYYY-MM-DD HH:mm:ss（默认 = 签发时间 + 24h）data.embed_urlstring拼接好的嵌入 URL（page 模式可直接使用），如 https://embed.maiya.ai/agents/{third_party_id}?token={token}

data.extra 结构

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

属性类型说明biz_varsobject业务变量实际值快照（接入方传入原值，不做 default 补全），含卡片展示固定字段 card_title、card_description、card_logo_url、card_price、card_unitsys_varsobject系统变量自动填充：channel（= third_party_id）、access_mode（接入模式）、issued_at（签发时间）

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 请求参数

参数名类型必填说明tokenstring是待吊销的 token

6.3 返回参数

参数名类型说明codeinteger200 成功messagestring响应消息data.token_idinteger已吊销的 token 记录 ID

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 流程图

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

步骤谁做做什么用到的接口/数据1. 获取 token第三方后端调用签发接口，传 third_party_id + biz_user_id + display_namePOST /assistant/access/token/issue，返回 data.token、data.embed_url2. 嵌入页面第三方前端用返回的 embed_url（或自行拼 token 到嵌入 URL），iframe / window.open 打开data.embed_url3. 用户进入终端用户打开嵌入页，平台自动校验 token、初始化聊天界面平台自动处理，第三方无感知4. 开始对话终端用户在聊天框发消息，接收 AI 回复平台自动处理5.（可选）吊销 token第三方后端用户登出或安全需要时吊销POST /assistant/access/token/revoke

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

8. 错误码与异常处理

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

8.1 错误码一览与处理建议

错误码触发场景说明第三方处理建议400third_party_id 不存在或已停用签发时查不到 is_valid=1 且 status=1 的接入配置核对 third_party_id 是否正确；确认接入配置是否被停用；联系我方重新开通

通用处理建议：

400 属配置类错误，重试无效，需先排查 third_party_id 配置。
签发接口建议做失败告警，持续 400 通常意味着接入配置变更。
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）。
密钥管理届时由我方分发，请勿将密钥硬编码到前端或提交到代码仓库。