换令牌与刷新

令牌端点：POST {issuer}/token，请求体为 application/x-www-form-urlencoded，响应带 Cache-Control: no-store。

客户端认证Copy Anchor Link

授权类型一：authorization_codeCopy Anchor Link

服务端的校验顺序：客户端认证 → 授权码存在且未使用 → redirect_uri 一致 → PKCE 通过 → scope 裁剪。

成功后同时返回访问令牌与刷新令牌（仅当 scope 含 offline_access 时才含刷新令牌），请求 openid 时还返回 id_token。

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "scope": "openid profile email offline_access",
  "id_token": "eyJ..."
}

expires_in 的数值由回调平台决定：web_server 为 3600 秒，公开客户端平台为 1800 秒。

授权类型二：refresh_tokenCopy Anchor Link

curl -X POST 'https://id.example.com/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=refresh_token' \
  -d "refresh_token=$REFRESH_TOKEN"

规则：

• scope 可选，且只能收窄：必须是原授权 scope 的子集，出现原授权之外的值会被拒。
• 每次刷新都轮换：返回新的访问令牌与新的刷新令牌，旧刷新令牌立即失效。请用新值覆盖存储，不要保留旧值做「兜底重试」。
• 刷新令牌是签名 JWT，客户端不要解析其内容，也不要假设其长度或格式稳定。
• 刷新不恢复 authorization_details：细粒度授权只在首次授权时成立，刷新后令牌不再携带。

授权类型三：client_credentialsCopy Anchor Link

只对 machine 客户端开放，用于服务端到服务端调用，不涉及用户。

curl -X POST 'https://id.example.com/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=client_credentials' \
  -d 'scope=auth:sessions:read'

• 签发的令牌没有 sub，用 principal 字段区分「代表用户」还是「代表应用」。
• 不能带 offline_access：没有用户就没有可刷新的会话，请求该 scope 会被判 invalid_scope。
• 第三方应用不需要这个授权类型；需要时说明产品形态应登记为 machine。

令牌交换Copy Anchor Link

第一方管理端可以用 RFC 8693 换取其他受众的令牌，第三方用不到，见 令牌交换。

错误响应格式Copy Anchor Link

令牌端点、撤销端点、内省端点遵循 RFC 6749 §5.2 的错误格式，不是控制台里那种统一信封：

{
  "error": "invalid_grant",
  "error_description": "The authorization code has already been used"
}

限流触发时返回 429，使用统一信封并带 Retry-After 头，详见 错误码。