第三方扫码接入

创建二维码

发送 POST 请求到 /api/auth/qr-sessions，无需预先登录。响应 data 包含 session_id、poll_secret、qrcode_url、expires_at 和 poll_interval_seconds。将 qrcode_url 作为图片展示给用户，不要向其他人公开 poll_secret。

查询与保存

按接口返回的 poll_interval_seconds 间隔请求 GET /api/auth/qr-sessions/{session_id}，通过 X-Scan-Secret 请求头提交 poll_secret。

curl 'https://你的域名/api/auth/qr-sessions/会话ID' -H 'X-Scan-Secret: 创建时返回的查询凭证'

• pending：继续等待用户扫码并关注服务号。
• confirmed：data.token 和 data.push_url 返回该扫码用户的完整凭证，保存后停止轮询。
• expired：停止轮询，需要时创建新的会话。
• 请求失败或用户关闭页面：停止轮询，并展示可重试提示。

会话有效窗口内可以重复查询，过期不再返回 Token。session_id 本身不能作为查询凭证，poll_secret 不应放在 URL 中。第三方服务可直接调用；第三方网页需要由管理员将其精确来源加入 allowed_origins。Token 仅授予向该用户推送的能力，不是管理凭证。