权限范围与可用 API

Scope 目录

授权页上给用户看的中文文案由 scope 决定 —— 申请得越多，用户越可能点「拒绝」。

Scope 与接口族的对应

写操作需要对应的 :write；有 :write 就隐含 :read（只判 read 的接口也放行）。

每个接口的具体读写语义、请求体与响应示例见业务 API 总览。

game:read / game:write 的边界

这两个 scope 是游戏数据的全部权限，但它们只在 /v1/games/** 上生效， 而且不越过"仅第一方"的线：

game:write 覆盖 game:read，但不会把上面两个"做不到"变成能做到：

第一方（RankHub App 与浏览器会话）不受这张表的限制 —— 它本来就是"用户本人"在用。

过渡例外：别名与谱面评论

曲目别名与谱面评论的 v1 形状还没设计，所以这两族在过渡期继续留在 /v0， 第三方仍可调用（scope 仍是 game:read|write / social:read|write）：

• GET|POST /v0/games/{game}/song-aliases/**、.../proposals/**；
• /v0/social/chart-reviews/**、/v0/social/posts/**/comments。

除此之外的 /v0/games/**、/v0/social/** 对第三方关闭。过渡期结束后这两族会迁到 v1， 届时会另行公告 —— 新代码不要围绕 /v0 的形状做长期设计。

调用方式

业务接口只有一个入口：https://api.rankhub.cc。

# 游戏档案（需要 game:read）
curl -s https://api.rankhub.cc/v1/games/maimai/profiles \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 开发者面（需要 development:read，返回 v1 信封）
curl -s https://api.rankhub.cc/v1/developer/oauth-apps \
  -H "Authorization: Bearer $ACCESS_TOKEN"

/v1/** 的响应带统一信封：

{
  "code": "common.ok",
  "message": "OK",
  "data": [],
  "requestId": "req_…"
}

/v0/** 的响应是直接的对象/数组（没有信封）。

只使用 api.rankhub.cc

业务接口只认 https://api.rankhub.cc。换成其他地址/端口会得到 401 —— 那不是 "令牌没生效"，而是这个入口不参与令牌鉴权。不要把这些地址写进配置。

401 / 403 / 428 / 429 怎么区分

刷新后 scope 会变吗

不会自动变。刷新返回的 scope 是当初授权时授予的那一组。要新增 scope，必须让用户重新走一次授权 （新请求里带上新的 scope 列表），旧的 refresh token 不会因此升级权限。

CORS

• 协议端点（auth.rankhub.cc 的 /v1/oauth/**、/v1/oidc/**）：会反射请求的 Origin 并带 Access-Control-Allow-Credentials: true，所以浏览器可以直接调（换令牌、userinfo、撤销）。
• 开发者 API（api.rankhub.cc/v1/developer/**）：只允许白名单来源 （OPEN_ALLOWED_ORIGINS，生产含 https://open.rankhub.cc）。第三方网页不要指望直连它 —— 那是给开发者平台自己用的。
• 业务接口（/v0/**、/v1/games/**）不保证对任意来源开放；需要浏览器直连的场景请先联系我们。