v1
v1 总览
v1 版本总览：三个上下文（auth / oauth / account）、基础路径与受众、接口组命名规则、v1 的状态与变更范围。
/v1 是当前唯一在用的版本。本页是 v1 的总览：它有哪些上下文、各自的基础路径与受众、接口组怎么命名、这个版本允许什么样的变更。
通用约定（认证方式、请求与响应格式、限流、缓存、时间与标识）在总览页统一说明，本页不重复。
上下文
| 上下文 | 基础路径 | 受众 | 主要使用方 | 页面 |
|---|---|---|---|---|
auth | {origin}/v1/auth | auth | 账户页、同意页；第三方读取用户信息 | auth 上下文 |
oauth | {issuer}（即 {origin}/v1/oauth） | oauth | 第三方授权与令牌、同意页内部端点 | oauth 上下文 |
account | {origin}/v1/account | account | 账户资料 | account 上下文 |
三者之间不共享数据，也不允许互相直接调用——跨上下文协作走事件。这决定了令牌不能跨上下文使用：auth 受众的令牌读不了 account 的数据，即使 scope 看起来够用。
接口组命名
- 组名取路径前缀的第一段：
/v1/auth/credentials/*属于credentials组，/v1/auth/session/*属于session组。 - 只有一个端点的路径前缀不单独成组，直接以端点名列出。
- 组名只用于文档归类，不是协议概念，不会出现在请求或响应里。
v1 的状态与变更范围
| 项 | 约定 |
|---|---|
| 兼容性变更 | 允许：新增端点、新增可选字段、新增错误码取值 |
| 破坏性变更 | 不允许，必须走 v2 |
| 字段语义 | 已有字段的语义与必填性在 v1 内不变 |
| 下线 | 仅在 v2 稳定后按公告并行下线，不会突然关闭 |
第三方需要哪些
| 需要什么 | 去哪 |
|---|---|
| 换取 / 刷新令牌 | oauth 上下文 的 token |
| 读取用户信息 | auth 上下文 的 userinfo |
| 校验令牌 | jwks（oauth 上下文）或 introspect（仅机密客户端） |
| 管理已授权应用 | oauth 上下文 的 grants |
其余接口服务于第一方账户页与同意页，第三方调用会被拒绝。判定依据见Scope 与受众。
文档结构
本版本按「上下文总览 → 接口组 → 端点」三层组织：
| 层级 | 位置 | 内容 |
|---|---|---|
| 上下文总览 | auth / oauth / account 的首页 | 该上下文有哪些接口组、认证方式、提权规则 |
| 接口组页 | 每个组一页 | 组内全部端点的路径、参数、响应与规则 |
| 端点 | 组页内的分节 | 逐字段说明与示例 |