快速开始

1. 创建 App

扫码登录开发者中心，在“应用管理”创建 App。App Secret 只显示一次；丢失后只能重置。

2. 请求登录二维码

调用 POST /api/open/login/qrcode。请求头：

请求头	值
`X-CL-App-Id`	App ID
`X-CL-Timestamp`	Unix 秒，允许前后 5 分钟
`X-CL-Nonce`	16–128 位随机字符串，10 分钟内不可重复
`X-CL-Signature`	HMAC-SHA256 十六进制小写签名

签名原文依次拼接并用换行分隔：HTTP 方法、路径、规范化查询串、timestamp、nonce、原始请求体 SHA-256。

成功响应同时包含 ticket、qrCodeBase64 和 expiresIn。直接把 Base64 Data URL 放到图片元素中展示。

3. 轮询结果

对 GET /api/open/login/status?ticket=... 使用同样的签名规则。状态为 success 时同时返回：

字段	稳定范围	用途
`unionUserId`	当前开发者名下的所有 App	在自己的多个 App 之间识别并共享同一用户
`appUserId`	当前 App	建立只属于当前 App 的独立用户记录

{
  "success": true,
  "data": {
    "ticket": "cl_xxx",
    "status": "success",
    "unionUserId": "cl_union_v1_xxx",
    "appUserId": "cl_app_user_v1_xxx"
  }
}

两个字段均由 Cool Login 对微信身份进行不可逆保护后生成，不是微信原始 OpenID 或 UnionID。同一微信用户登录同一开发者的不同 App 时，unionUserId 相同而 appUserId 不同。结果窗口为 30 秒，之后返回 expired。

不要在浏览器里生成签名或暴露 App Secret。轮询必须由你的服务端完成。

使用托管登录页

如果不想自行展示二维码和维护轮询页面，可以使用 Portal 便捷登录。Cool Login 会完成二维码展示和扫码状态确认，再携带原 ticket 返回你的应用；你的服务端对现有状态接口查询一次即可。