接口参考

接口参考（OAuth / SSO）

Base URL（生产）：https://auth.geekhonize.top　本地开发：http://localhost:8787 所有端点在 /api/v1/auth/ 下，请求/响应均为 JSON；非 JSON 请求体返回 415。

本文是 SDK 背后的原始协议。日常接入直接用 SDK，不必手写这些。 密码/邮箱验证码等完整端点清单见 SSO 仓库 docs/api.md。

统一信封

// 成功
{ "ok": true, "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 604800, "user": { … } }
// 失败
{ "ok": false, "msg": "账号或密码错误" }

200 成功，4xx 客户端错误，500 服务端错误。msg 为中文可读信息。

访问令牌（JWT, HS256）

默认有效期 7 天。⚠ HS256 是共享密钥签名——第三方无法本地验签，核实身份必须调 /me。

授权码流程端点

GET /authorize（浏览器跳转，非 API）

账号中心授权页。参数：client_id、redirect_uri、state、scope（公开客户端再加 code_challenge、code_challenge_method=S256）。用户同意后回跳 redirect_uri?code=&state=。

POST /api/v1/auth/client_info（免鉴权）

授权页用它校验应用与回调。请求 { client_id, redirect_uri }，返回 data.{ client_id, display_name, homepage, scopes, redirect_ok, client_type, pkce_required }。 不含 secret，不返回完整白名单。

POST /api/v1/auth/authorize（Bearer）

已登录用户为某应用签发一次性授权码。请求 { client_id, redirect_uri, state?, scope?, code_challenge?, code_challenge_method? }， 返回 data.{ code, redirect_url, expires_in }。授权码 2 分钟有效、单次使用。 公开客户端必须带 code_challenge（仅 S256）。

POST /api/v1/auth/exchange（免 Bearer）

用授权码换令牌。请求 { client_id, code, client_secret?, code_verifier? }。

成功返回与 login 相同的令牌信封（外加 scope）。授权码重放 / 过期 / verifier 不匹配均以 400/401 拒绝。

会话端点

• GET /api/v1/auth/me（Bearer）—— 复核身份，返回 data.{ uid, username, display_name, email, email_verified, roles, app, exp }。
• POST /api/v1/auth/refresh（Bearer）—— 续期，返回新令牌信封。
• POST /api/v1/auth/logout（Bearer 可选）—— 无状态，客户端丢弃令牌即可。

CORS（浏览器直调）

SDK 浏览器端跨域调用：client_info / authorize / exchange / me / refresh / logout。

• 应用可登记 cors_origins；留空时回落到 redirect_uris 的 origin 集合。
• 命中白名单才回显精确 Origin（绝不用 *），并带 vary: Origin。
• OPTIONS 预检同样校验，路径带 ?client_id=… 可走单行查询。
• 密码端点（register/login）不开放跨域。
• 白名单改动对预检最多延迟 60 秒（模块级缓存）生效；正文校验不受影响。

应用自助管理（Bearer）

由开发者平台使用，一般不直接调：

其它登录方式

• 设备码（桌面/游戏/启动器，无浏览器输密码）：POST /device/start → 展示 6 位码 →

用户在浏览器 POST /device/approve（Bearer）→ 客户端 POST /device/poll 轮询拿令牌。

• 长期游戏令牌：POST /game_token（Bearer）签发 30 天、app=breakfront 的令牌，用于游戏内粘贴登录。

错误信息对照（OAuth 相关）