酷码开放平台

平台简介

酷码开放平台基于 OAuth 2.0 授权码模式（Authorization Code），让第三方软件通过酷码统一账号体系完成登录验证。用户授权后，你的应用获取 access_token，可读取用户的昵称与头像。

适用场景：桌面应用、小程序、任何想要"用酷码账号登录"的软件。

快速开始

授权流程

你的软件                    酷码账号中心                        用户
   │  ① 调用 /api/authorize-url.php   │                       │
   │──────────────────────────────────▶│                       │
   │  ② 返回授权地址                    │                       │
   │◀──────────────────────────────────│                       │
   │  ③ 系统浏览器打开授权地址 ────────────▶ 用户登录 + 点击授权确认  │
   │                                   │◀─────────────────────▶│
   │  ④ 授权成功后带 code+state 回跳      │                       │
   │◀──────────────────────────────────│                       │
   │  ⑤ code+appSecret 调 /api/token   │                       │
   │──────────────────────────────────▶│                       │
   │  ⑥ 返回 access_token              │                       │
   │◀──────────────────────────────────│                       │
   │  ⑦ 携 access_token 调 /api/userinfo│                       │
   │──────────────────────────────────▶│                       │
   │  ⑧ 返回用户信息                    │                       │
   │◀──────────────────────────────────│                       │

软件端接入示例

以 Electron / C# / 任意桌面程序为例，核心就三步：取授权 URL → 用系统浏览器打开 → 本地回调收 code 换 token。

JavaScript（Electron / 浏览器）

// ① 获取授权 URL（浏览器可用原生 fetch，Node/Electron 若无 fetch 用 axios 等）
const resp = await fetch(
  'https://kuma2.cn/api/authorize-url.php' +
  '?client_id=' + encodeURIComponent(APP_ID) +
  '&redirect_uri=' + encodeURIComponent(REDIRECT_URI) +
  '&state=' + state
);
const { authorize_url } = await resp.json();

// ② 打系统浏览器打开授权站（用户登录 + 授权后自动回跳 RETDIRECT_URI?code=...&state=...）
require('child_process').exec('start "" "' + authorize_url + '"');   // Windows
// macOS / Linux: open 或 xdg-open

// ③ 本地回调端口收到 code 后，后端换取 access_token
const token = await fetch('https://kuma2.cn/api/token.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: 'code=' + encodeURIComponent(code) +
        '&client_id=' + encodeURIComponent(APP_ID) +
        '&client_secret=' + encodeURIComponent(APP_SECRET) +
        '&redirect_uri=' + encodeURIComponent(REDIRECT_URI)
}).then(r => r.json());

// ④ 用 access_token 查询用户
const me = await fetch('https://kuma2.cn/api/userinfo.php', {
  headers: { 'Authorization': 'Bearer ' + token.access_token }
}).then(r => r.json());
console.log(me.user.nickname);

桌面程序常见回调方式：开启一个 http://127.0.0.1:端口/callback 的本地 HTTP 服务，把该地址注册为应用回调；授权成功后浏览器跳转到这里，本地服务捕获 code 后自动关闭浏览器窗口，完成令牌交换并存下登录态。

接口一览

6. 获取授权 URL

软件端第一步：调用本接口拿到一个可直接交给系统浏览器打开的授权地址。

{
  "ok": true,
  "authorize_url": "https://kuma2.cn/account/authorize?client_id=capp_xxx&redirect_uri=https%3A%2F%2F...&state=abc",
  "client": "我的应用名"
}

若 client_id 无效或 redirect_uri 与注册不一致，将返回 ok:false 并给出 400 错误。

7. 换取 access_token

用户授权后，浏览器会带着 code（和 state）跳回你的回调地址。你的软件用该 code 向后端换取令牌。

{
  "ok": true,
  "access_token": "f0c4...",
  "token_type": "Bearer",
  "expires_in": 600
}

8. 查询用户信息

{
  "ok": true,
  "user": {
    "id": 12,
    "email": "user@example.com",
    "nickname": "小码",
    "avatar": "/uploads/avatars/xxxx.png"
  }
}

9. 错误码

10. 安全建议

• state 参数：生成随机串，回跳时比对，防止跨站请求伪造。
• 回调地址：线上必须 https；redirect_uri 必须与注册值完全一致。
• appSecret：仅存后端，绝不写入客户端或前端代码；泄露立即在开发者中心重置。
• access_token：有有效期，请妥善存储，泄露后可重置应用密钥使其全部失效。
• 授权码：一次性，切勿复用或缓存。

11. 常见问题

Q：桌面应用的回调地址填什么？
A：建议在软件内本地启动一个回调端口（例如 http://127.0.0.1:18000/callback），把该地址填入应用设置。auth 完成后浏览器带 code 访问此地址，本地服务捕获后即可继续换取令牌。

Q：为什么提示"回调地址与注册不一致"？
A：你传的 redirect_uri 与控制台注册的值不完全相同（包括 http/https、端口、末尾斜杠）。请逐字符核对。

Q：appSecret 丢了怎么办？
A：在开发者中心点击"重置密钥"，旧密钥立即失效，会重新生成一个。

Q：授权码有效期多久？token 呢？
A：授权码 10 分钟且一次性；access_token 默认 10 分钟，过期需重新授权。