概览与快速开始

RankHub 的 OAuth 2.1 / OIDC 接入全貌：平台地址、端点清单、客户端类型与五分钟上手路径。

RankHub 对外提供一套 OAuth 2.1 + OIDC 能力：第三方应用可以让用户用 RankHub 账号登录，并在用户授权后代表其访问 RankHub 的接口。

开发者平台（注册应用、拿凭据、看统计）：open.rankhub.cc
授权与 OIDC 端点所在域：https://auth.rankhub.cc
业务 API（拿到令牌后调用）：https://api.rankhub.cc

三件必须先知道的事

授权确认发生在 RankHub App 里。浏览器打开的是同意页，但它只负责把请求交给用户手机上的 RankHub App（深链或二维码），用户在 App 内批准或拒绝。纯网页登录态不能代替这一步。
应用必须过审。在开发者平台注册后状态是「审核中」，未通过审核的应用做授权/换令牌一律返回 invalid_client。
业务接口只经 https://api.rankhub.cc。直连后端宿主端口不会被认作已登录（401）。

端点清单

用途	地址
发现文档（OIDC Discovery）	`https://auth.rankhub.cc/v1/oidc/.well-known/openid-configuration`
公钥集（JWKS）	`https://auth.rankhub.cc/v1/oidc/jwks`
授权页（给人看，托管同意页）	`https://auth.rankhub.cc/oauth/authorize`
设备确认页（输入 `user_code`）	`https://auth.rankhub.cc/oauth/device`
授权端点（协议面，返回 JSON）	`https://auth.rankhub.cc/v1/oauth/authorize`
令牌端点	`https://auth.rankhub.cc/v1/oauth/token`
用户信息	`https://auth.rankhub.cc/v1/oidc/userinfo`
撤销令牌	`https://auth.rankhub.cc/v1/oauth/revoke`
自省令牌	`https://auth.rankhub.cc/v1/oauth/introspect`
设备授权（RFC 8628）	`https://auth.rankhub.cc/v1/oauth/device_authorization`
前端接入脚本（JS SDK）	`https://auth.rankhub.cc/oauth/sdk.js`

发现文档不在标准路径

OIDC 的 issuer 是 https://auth.rankhub.cc，但发现文档实际挂在 /v1/oidc/.well-known/openid-configuration —— 根路径 /.well-known/openid-configuration 返回 404。通用 OIDC 库按「issuer + /.well-known/openid-configuration」自动发现会失败，必须手动指定发现地址（或直接手填端点）。详见OIDC 与用户身份。

选一种接入方式

Web 前端（推荐）

公开客户端 + PKCE。用 JS SDK 一行脚本挂登录按钮，或自己走授权码流程。

服务端 / 机密客户端

有后端、能保管 client_secret。标准授权码 + PKCE + 刷新。

只做「用 RankHub 登录」

只要 id_token 和用户资料：授权码拿到 openid 后就够了。

桌面 / CLI

设备码流：设备显示短代码，用户在确认页输入并在 App 内批准。

客户端类型怎么选

	公开客户端（public）	机密客户端（confidential）
注册时 `Token endpoint authentication`	`none`	`client_secret_post` 或 `client_secret_basic`
`client_secret`	没有	有，只在创建/轮换时展示一次
PKCE	强制 `S256`	可选（注册时未要求则不校验）
适合	浏览器 SPA、移动端、桌面端	有服务端的 Web 应用、后端任务
能不能在浏览器里换令牌	能（没有 secret 可泄露）	不能，`client_secret` 不能进浏览器

支持的协议子集

能力	状态
`authorization_code` + PKCE（`S256`）	支持
`refresh_token`（轮换 + 重放检测）	支持
`device_code`（RFC 8628）	支持（托管确认页 `/oauth/device`，见设备码流）
`id_token`（ES256 签名）+ userinfo	支持
令牌自省 / 撤销	支持
可内嵌授权面（`/oauth/embed`）	支持，但需要登记来源（见 JS SDK）
`implicit`、密码模式（ROPC）	不支持
`response_mode` 除 `query` 外	不支持
`request` / `request_uri`（JAR）、`id_token_hint`	不支持
`end_session` / RP 发起的登出	不支持（用撤销令牌代替）
动态客户端注册（DCR）、`private_key_jwt`	不支持（在开发者平台注册）

拿到令牌之后：业务 API

OAuth 只解决「用户是谁、应用被授权了什么」。要读写游戏数据，再用 access token 调 https://api.rankhub.cc。游戏数据只有一个面：/v1/games/**（旧的 /v0 游戏接口只服务 RankHub 自有客户端）。

业务 API 总览

路径族、Bearer 鉴权、scope 判定、能力矩阵、分页与限流。

游戏档案

档案读取、来源标记、推档案建号与删除申请。

成绩读取与写入

读成绩/最佳成绩；maimai、Arcaea 支持第三方批量写入。

曲目别名投票

按别名找曲目、提提案与社区投票（过渡期仍在 /v0）。

谱面评分与评论

1–5 星评分、按曲目聚合统计与评论串（过渡期仍在 /v0）。

scope 决定能做什么，形状决定能不能调

/v1/games/** 按 game:read / game:write 判定；写覆盖读。缺 scope 是 403，不是 401 —— 重新授权补 scope 才能解决。但 scope 补不齐"仅第一方"的形状（导入 / 同步 / 任务 / 机台中转 / 删除审批），那些一律 403 game.firstPartyOnly，边界见权限范围与可用 API。