总览
API 文档的组织方式（总览 → 版本 → 上下文 → 接口组）、版本一览，以及跨版本通用的请求与响应约定。
本板块给出对外 HTTP API 的说明。它按「总览 → 版本 → 上下文 → 接口组」四层组织，本页是第一层：先说明整体结构，再给出所有版本都适用的通用约定。
组织方式
| 层级 | 内容 | 位置 |
|---|---|---|
| 总览 | 结构说明、版本一览、通用约定 | 本页 |
| 版本 | 一套独立的接口契约，路径里的 /v1、/v2 | v1、v2 |
| 上下文 | 服务器上的限界上下文，同时也是令牌受众 | 版本页内的上下文介绍 |
| 接口组 | 同一路径前缀下的一组端点 | 上下文页内的接口组表 |
四层不是文档分类习惯，而是实现结构：版本前缀挂在路由根上，上下文是下一段路径，接口组是再下一段。所以 URL 本身就是目录——/v1/oauth/grants 对应「v1 → oauth → grants」。
版本一览
上下文与受众
| 上下文 | 基础路径 | 受众 | 主要使用方 |
|---|---|---|---|
auth | {origin}/v1/auth | auth | 账户页、同意页；第三方读取用户信息 |
oauth | {issuer}（即 {origin}/v1/oauth） | oauth | 第三方授权与令牌、同意页内部端点 |
account | {origin}/v1/account | account | 账户资料 |
上下文之间不共享数据，令牌不能跨上下文使用：拿着 auth 受众的令牌读不了 account 的数据，即使 scope 看起来够用。
地址与版本
- 版本号写在路径里（
/v1/），不在请求头里；不存在用Accept-Version协商的写法。 - 同一版本内只做兼容性变更：新增端点、新增可选字段、新增错误码取值。已有字段的语义与必填性不变。
- 破坏性变更一定伴随新版本，旧版本并行一段时间后按公告下线，不会在同一路径上悄悄改变行为。
- 实际地址一律以元数据发现的返回值为准，不要硬编码域名。
认证
| 场景 | 方式 |
|---|---|
| 资源接口（UserInfo、账号管理） | Authorization: Bearer <access_token> |
令牌接口（token / revoke / introspect） | 客户端认证：client_secret_basic 或 client_secret_post；公开客户端仅传 client_id |
不支持的认证方式一律返回 401，不会「尽量尝试」——降级尝试只会把认证失败伪装成参数错误。
请求格式
- 令牌相关端点：
Content-Type: application/x-www-form-urlencoded。 - 同意页与内部端点：
Content-Type: application/json，且只接受POST。 - 资源接口：
GET无请求体；写入类接口使用 JSON 请求体。
响应格式
两套并存，按端点区分，客户端必须都能解析：
| 端点类别 | 成功响应 | 错误响应 |
|---|---|---|
协议端点（token / revoke / introspect） | 扁平 JSON（access_token、expires_in 等） | RFC 6749 §5.2：{ "error": "...", "error_description": "..." } |
| 资源与管理端点 | 扁平 JSON | 统一信封：{ success, code, message, details?, timestamp } |
完整错误码见错误码。
限流
- 按端点独立计数，同时存在全局限流。
- 超限返回
429，响应带Retry-After（秒）。 - 客户端应遵守
Retry-After；批量场景使用随机退避，不要固定间隔重试。
缓存
| 响应 | 缓存头 |
|---|---|
| 令牌相关端点 | Cache-Control: no-store，不得缓存 |
jwks | 可缓存 5 分钟，按 kid 匹配公钥 |
| 资源接口 | 不缓存用户数据 |
时间与标识
- 时间统一为 Unix 秒（
auth_time、iat、exp）或 ISO 8601 UTC 字符串（timestamp）。 - 用户标识使用
sub，全局稳定且不可预测；不要用邮箱、昵称做账号主键。 - 分页接口使用游标或页码参数，具体以端点页为准。
第三方先读哪里
逐字段的接口文档正在按版本与上下文补齐；在补齐之前，上面四页已覆盖第三方接入所需的全部内容。