核心概念

本指南会帮开发者理解：你属于哪一层扩展、走哪种集成模式、wsa 令牌里有什么、以及你要「用到什么程度」。

两种集成模式：推式 vs 拉式

平台把身份交给你，有两条路径。同一枚 wsa 契约，区别只在「你如何拿到身份鉴权信息」。

推式（Push handoff）—— 见 03

用户在工作空间「扩展」页里点开你的应用，平台把 wsa 拼到你的落地页 URL 上推给你：

https://app.example.com/landing?wsa=<JWT>

                      
                      https://app.example.com/landing?wsa=<JWT>

此代码块在浮窗中显示

入口在工作空间内。
开发者只需在落地页消费 ?wsa=，最简单。
适合：作为工作空间侧边栏里的一个「内嵌应用」。

拉式（Pull / M-Auth）—— 见 04

开发者的扩展应用自己放一个「Login with Workspace」按钮，用户点击后进入 GPTBots 登录➡️选工作空间➡️再带回登录态。采用 OAuth2 授权码 + PKCE：

入口在开发者的扩展应用登录页。
浏览器只拿到一次性 code，真正的 wsa 由你的后端用 code + PKCE 换取，永不进浏览器 URL。
适合：开发者的扩展应用是独立站点，希望提供「用 GPTBots 工作空间账号登录」。

	推式 Push	拉式 Pull (M-Auth)
登录入口	工作空间「扩展」页	你的应用页面（登录按钮）
令牌怎么到你手上	URL `?wsa=` 直接推给落地页	前端拿 `code`，后端换 `wsa`
浏览器是否见过 `wsa`	见过（落地后须立即抹除）	从不（更安全）
需要 PKCE	否	是（强制 `S256`）
SDK 前端方法	`consumeHandoff`	`startWorkspaceLogin` + `completeWorkspaceLogin`

身份鉴权信息使用指南

平台只负责「传递身份」，是否使用由开发者独立决定：

档位	含义	开发者要做的
`use`	验签 + 建立会话 + 按 `role` 门控功能	`consumeHandoff` / `completeWorkspaceLogin`，后端 `verifyWsa`
`receive-only`	读取身份用于展示/埋点，但不建会话、不门控，继续用自有鉴权或匿名	仅 `readHandoffToken()`（纯函数，无副作用）
`ignore`	完全不读，等同 `auth_mode=none`，就是一个普通外链	什么都不做

verifyWsa / readHandoffToken 都是纯函数，所以「接收但不使用」是零成本的。

对应到注册时的 auth_mode：

auth_mode = workspace_account：平台会签 wsa 拼到 URL（推式）/ 支持 M-Auth（拉式），你能拿到身份。
auth_mode = none：平台直接跳转，URL 不带任何鉴权信息，你收不到身份（对应 ignore）。

`wsa` 令牌契约（JWT）

wsa 是一枚 HS256（HMAC-SHA256）签名的 JWT，有效期 5 分钟（exp = iat + 300）。

标准声明

声明	类型	说明
`iss`	string	固定 `gptbots-workspace`，必校
`aud`	string	开发者扩展应用 host（如 `app.example.com`），从注册 URL 解析，必校
`sub`	string	工作空间用户 `accountId`，全局唯一，可作为开发者侧的用户 ID 主键
`iat`	number(秒)	签发时间
`exp`	number(秒)	过期时间，固定 `iat + 300`，必校

业务声明

声明	类型	说明
`role`	string	`OWNER` / `ADMIN` / `MEMBER` —— 用户在该工作空间的角色
`workspace_id`	string	工作空间 ID（即 `projectId`），多租户隔离键
`username`	string	用户昵称（可能缺省）
`email`	string	用户邮箱（可能缺省）
`avatar`	string	头像 URL（可能缺省）
`app_name`	string	当次跳转对应的扩展应用名（便于审计，可能缺省）

缺省字段：username / email / avatar / app_name 在源数据为空时不会出现在 payload 里，请务必做空值兜底，不要假设它们必然存在。

示例 payload

{ "iss": "gptbots-workspace", "aud": "app.example.com", "sub": "65f7c8a1d8f3a40012345678", "iat": 1730000000, "exp": 1730000300, "username": "张三", "email": "zhangsan@example.com", "avatar": "https://cdn.example.com/avatar/u123.png", "role": "ADMIN", "workspace_id": "65a0000000000000000abcde", "app_name": "合同审核系统" }

                      
                      {
  "iss": "gptbots-workspace",
  "aud": "app.example.com",
  "sub": "65f7c8a1d8f3a40012345678",
  "iat": 1730000000,
  "exp": 1730000300,
  "username": "张三",
  "email": "zhangsan@example.com",
  "avatar": "https://cdn.example.com/avatar/u123.png",
  "role": "ADMIN",
  "workspace_id": "65a0000000000000000abcde",
  "app_name": "合同审核系统"
}