OAuth 授权流程
两种授权模式的完整流程、时序设计与 Token 生命周期管理。
OAuth 各接口的完整字段说明，参见 认证模块 - 场景说明。本页聚焦于集成方实施 OAuth 的完整指南，包含模式选择、指定 Space 模式完整时序与 Token 生命周期管理。
授权模式选择
| 维度 | 开放模式 | 指定 Space 模式 |
|---|---|---|
| 适用场景 | C 端用户，每个邮箱独立发起授权 | 企业/组织场景，用户归属 Space 由集成方预先指定 |
授权 URL 是否传 space_id | 否 | 是（同时传 login_hint） |
| 用户是否需预添加 | 否（未注册则静默注册并创建默认 Space） | 是（需先调用 预添加成员 接口） |
| 授权页是否展示 Space 选择器 | 是 | 否（Space 已由服务端锁定） |
| Space 自动创建 | 是（未注册用户首次授权时） | 否 |
当集成方需要将用户严格归属到指定企业 Space 时，选择指定 Space 模式；否则默认采用开放模式，由用户自行选择或由系统创建 Space。
授权流程图
异常分支（用户取消、拒绝授权、账号被禁用 / Space 锁定等）按 RFC 6749 §4.1.2.1 规范统一以 error=access_denied 形式 302 回 redirect_uri。Get Started 页对新用户自动静默注册并创建默认 Space（该用户为管理员）；存量用户登录后展示其加入的 Space 列表（标注角色与安装状态），由用户自行选择。
接口时序
client_secret 与 refresh_token 涉及凭据保管，建议放在集成方信任域内，具体存储与代换边界由集成方按自身架构决定。
指定 Space 模式
指定 Space 模式在开放模式的基础上，增加了「成员预添加」前置步骤，并在 SubmitConsent 阶段自动激活待激活成员。
两条激活路径互不影响：用户可以通过 OAuth 授权页点「同意」激活成员，也可以直接点击邀请邮件中的链接完成激活，两种方式均有效，以先完成者为准。
Token 生命周期
| 场景 | 行为 |
|---|---|
| access_token 过期 | 用 refresh_token 换新 access_token + 新 refresh_token |
| refresh_token 永久有效，不会过期 | 无需重新授权（如泄漏请调用 revoke 接口撤销） |
| 用户在 Tencent eSign 侧撤销集成应用授权 | 该用户/Space 的 access_token、refresh_token 进入黑名单立即失效；继续调用业务接口将返回 401 invalid_token，集成方应清理本地对应 token，下次用户使用时重新发起 OAuth |
| 同一用户在新设备重新发起 OAuth 并完成授权 | 旧 refresh_token 不会立即失效，新旧 token 可能共存；具体保留策略以服务端实现为准 |
| 集成方主动撤销 token | 调用 令牌撤销端点 |
每次 refresh_token 刷新都会返回新的 refresh_token，旧值立即失效（滚动刷新）。请用新值替换原值，否则下次刷新会失败。返回的 token 已绑定授权页选定的 Space，调用业务 API 时无需再传 space_id。
Scope 取值
| scope | 说明 |
|---|---|
envelope:create | 创建并发送信封（“发起签署”必需） |
envelope:read | 读取信封列表与状态（“签署状态”必需） |
envelope:manage | 管理信封（创建、发送、下载、查看等）— envelope:create + envelope:read 的超集，新集成方推荐使用 |
stamp:manage | 管理印章（创建、编辑、删除、查看等） |
template:manage | 管理模板（创建、编辑、删除、使用等） |
member:manage | 管理成员（预添加、激活等） |
未来如新增 scope，将通过版本更新通告，不会破坏既有 scope 语义。