OAuth 代理用户授权

写接口（发帖、点赞、上传等）涉及真实用户的资源，因此除应用自身的 API Key + 签名外，还需要用户的 access token。这是一个 OAuth 2.0 风格的授权码流程。

流程概览

你的应用 → 引导用户到平台授权页 → 用户同意 → 平台 redirect 回你 + auth_code
        → 应用用 auth_code 兑换 access token (24h 有效)
        → 后续写接口带 X-Proxy-Access-Token

1. 申请 user:proxy 权限

在应用审批时勾选 user:proxy 是前置条件。

2. 跳转授权页

引导用户访问：

https://www.example.com/openapi-authorize?app_id={你的appId}&redirect_uri={URL_ENCODED}

用户在平台登录态下点同意后，回跳到你的 redirect_uri，URL 拼上：

?auth_code=6位code

auth_code 仅 5 分钟内、仅一次有效。

3. 兑换 access token

后端发起：

POST /openapi/v2/oauth/token
Content-Type: application/json
X-API-Key: ...
X-Timestamp: ...
X-Signature: ...

{ "userId": 1234, "authCode": "ABC123" }

成功响应：

{
  "code": 0,
  "data": {
    "accessToken": "<32 位 token>",
    "userId": 1234,
    "scopes": ["post:write", "comment:write"],
    "expiresAt": "2026-05-30 12:00:00"
  }
}

24 小时后自动失效；接近过期可重新走授权流程拿新 token，不要硬编码到代码里。

4. 调用写接口

POST /openapi/v2/mods/draft/init
X-API-Key: ...
X-Timestamp: ...
X-Signature: ...
X-Proxy-Access-Token: <accessToken>

{ "sectionCode": "...", "title": "..." }

拦截器会自动用 accessToken 解析出 userId 并覆盖 X-Proxy-User-Id（防伪造）。

5. 撤销 token

POST /openapi/v2/oauth/revoke
X-Proxy-Access-Token: <accessToken>

用户退出登录、应用撤回授权时调用一次。

错误码

错误码	说明
200205	应用未开通 user:proxy 权限
200911	authCode 无效 / 已过期 / 已被使用
200912	authCode 与提交的 userId 不匹配

最佳实践

• accessToken 不要落本地 localStorage —— 写后端持久层并 加密存储
• 单 token 复用，避免高频颁发
• 检测 expiresAt，过期前提前刷新（重新发起授权）
• 业务侧也尊重用户撤回授权的诉求，及时主动 revoke