注册应用与凭据
在 open.rankhub.cc 创建 OAuth 应用、填回调与 scope、过审、轮换 secret，以及平台的各种硬限制。
所有客户端都在 开发者平台 open.rankhub.cc 上自助注册，没有别的注册入口。
创建流程
登录开发者平台
打开 open.rankhub.cc，用 RankHub 账号登录。确认动作在 RankHub App 内完成 （与第三方授权是同一条链路），令牌只保存在该站点自己的浏览器存储里。
新建 OAuth App
进入 OAuth Apps → 注册 OAuth App，填写下表，勾选「我已阅读并遵守写入政策」， 点 提交审核。
等审核
新应用状态是「审核中」，此时不能用于授权或换令牌。管理员通过后状态变为「活跃」， 就可以开始接入；被拒绝会变成「已拒绝」，改完配置点 重新提交审核 即可再进队列。
记下凭据
创建成功后弹窗会展示 Client ID 与（机密客户端才有的）Client Secret。 secret 只展示这一次，关闭弹窗后就再也拿不到，只能轮换。
表单字段
| 字段 | 必填 | 说明 |
|---|---|---|
| 名称 | 是 | 会显示在用户授权页上（「XX 请求访问你的账号」），填真实产品名 |
| 应用主页 | 否 | 展示用，建议填 |
| Logo URL | 否 | 展示用，建议 https |
| 回调地址（Redirect URIs） | 是 | 每行一个；规则见下 |
| Post Logout Redirect URIs | 否 | 目前没有任何端点使用它（本平台不支持 RP 发起的登出），登记了也只是留档 |
| Token endpoint authentication | 是 | none = 公开客户端；client_secret_post / client_secret_basic = 机密客户端。创建后不能修改 |
| Scopes | 否 | 空格或逗号分隔，默认 openid profile；越界会 400。留空等于拿到全部 17 个 scope，不建议 |
| 可嵌入来源（Embed Origins） | 否 | 每行一个裸 origin（如 https://app.example.com）。只有登记过的页面才能用 JS SDK 内嵌授权面；留空 = 禁止内嵌。规则见下 |
回调地址的硬规则（前端校验，服务端按字符串比较）：
- 最多 20 条，
https开头；只有localhost/127.0.0.1允许http（本地开发）； - 不得包含
*通配、#片段、userinfo（https://user:pass@host）； - 逐字精确匹配：授权请求里的
redirect_uri必须与这里登记的某一项完全一致（包括大小写、末尾斜杠）， 不做前缀/通配匹配。手机原生应用请用https通用链接或http://127.0.0.1:端口回环。
状态与操作
| 状态 | 含义 | 能否授权 |
|---|---|---|
| 审核中（pending） | 等待平台审核 | 否（invalid_client） |
| 活跃（active） | 审核通过且启用 | 是 |
| 已拒绝（rejected） | 审核未通过，可改后重新提交 | 否 |
| 已停用（inactive） | 自建停用，可再启用 | 否 |
| 已暂停（suspended） | 平台运营暂停 | 否 |
| 已撤销（revoked） | 永久撤销，不可恢复 | 否 |
可用操作：
- 轮换 secret：立即生成新 secret 并作废旧值 —— 正在用旧值的线上服务会立刻换令牌失败，请配合发布窗口。
- 停用 / 启用：只是把客户端标记为不可用。
- 撤销：不可恢复；会原子地撤销该应用名下所有令牌族、已签发令牌与待用授权码。
- 重新提交审核：把被拒绝的应用重新送入审核队列。
撤销与停用的连带影响
撤销或停用后，已经拿到令牌的用户也需要重新授权。上线中的产品不要用「撤销」做临时止血， 用「停用」再恢复。
写入政策与「停写」
提交审核之前必须先确认写入政策（注册表单里有这一项，不勾选无法提交）。它约束应用
怎么使用 game:write，长期有效 —— 过审不等于拿到"随便写"的许可：
- 只提交在你这一侧真实产生的数据，不伪造、不批量灌库；
- 只能"推数据"，不能代替用户从游戏平台导入 / 同步（那些入口只给 RankHub 自己的客户端）；
- 删除档案不能直删，只能提交删除申请，由用户在 RankHub 里确认；
- 平台会校验可疑写入：低频单次异常可能要求用户确认后重试；批量、连续或明显异常的写入会 暂停该应用的写权限；
- 接口调用按应用限流，触发时按
Retry-After退避。
规则的对外条款见业务 API 总览、游戏档案、 成绩读取与写入；码与处理见错误与排障。
停写状态在哪看
停写会在开发者平台的应用详情里显示：状态为「写权限已暂停」，并给出原因与触发时间。 它和应用状态（审核中 / 活跃 / 已暂停 …）是两件事：
| 停写 | 应用暂停（suspended） | |
|---|---|---|
| 谁触发 | 平台自动（异常写入），或运营手动 | 运营，重复违规 / 恶意行为 |
| 影响范围 | 只拦写：读、登录、刷新令牌都正常 | 无法授权、无法换令牌 |
| 在哪里看 | 应用详情的写入政策区 | 应用状态 |
| 怎么恢复 | 联系平台说明用途与数据来源 | 走既有审核流程 |
恢复只能由平台执行。换 client secret、重新授权、重试都不会解除停写 ——
遇到 403 game.writeSuspended 请先停下来核对自己的数据来源。
配额与限制
| 限制 | 值 |
|---|---|
| 每个账号可拥有的 OAuth 应用 | 5 个 |
| 每个应用的回调地址 | 20 条 |
| 认证方式 | 创建后不可修改 |
| 明文 secret | 只在创建 / 轮换时返回一次 |
| 授权请求有效期 | 5 分钟（待 App 确认的窗口） |
| 授权码有效期 | 10 分钟，一次性 |
| access token | 600 秒（默认，可由平台运维调整） |
| refresh token | 30 天（默认），每次刷新都轮换 |
Scopes
申请时填的 scope 决定用户会被请求哪些权限，也决定你能拿到哪些数据。
- 默认值
openid profile；openid会被自动补上（缺了也加回来）； - 只能填这 17 个：
openid、profile、email、phone、offline_access，以及profile:read、profile:write、account_security:read、account_security:write、event:read、event:write、social:read、social:write、game:read、game:write、development:read、development:write； - 不在列表里的会 400
Unsupported scopes: …； - 留空 = 拿到全部 17 个（服务端把空数组展开成全量）。请显式填写，不要留空。
授权时客户端请求的 scope 必须是「默认的 openid profile」∪「注册的 scope」的子集，
越界返回 400 Unsupported scope: …。scope 与接口的对应关系见权限范围与可用 API。
可内嵌来源（Embed Origins）
如果要用 JS SDK 的内嵌模式 把授权面 iframe 进自己的页面， 把宿主页面的裸 origin 填进这个字段（创建或编辑应用时都可以改）。
- 只接受
https://app.example.com[:port]这种裸 origin：不要带路径、查询、片段或user.name@这类 userinfo； http仅限localhost/127.0.0.1/[::1]（本地开发）；- 最多 20 条，会去重、小写 host、去掉默认端口；
- 保存后会立即生效（不需要重新审核），但只影响内嵌授权面（
/oauth/embed）能否被框住， 不影响小窗流程与回调地址校验。
登记一个来源 = 允许把这个客户端的授权码交付给它（内嵌模式直接把结果 postMessage 给宿主），
所以只登记你自己控制的域名。未登记的来源会看到「当前站点未注册为可内嵌来源」，
且不会创建任何授权请求。
统计
平台的 概览 / 统计 页可以按应用查看授权次数、活跃令牌数、刷新与撤销次数、错误率等， 用来判断接入是否健康。这些数字来自事件记录，不会保存令牌、授权码、secret 或 DPoP proof。