API 参考文档

AuthGuard 当前已经按“软件授权验证平台”主线组织接口，重点不是普通后台 CRUD，而是围绕客户端接入的 /api/verify/*。

当前公开验证层已经把网站与接口收敛到同一条主链路；下面文档以仓库当前真实实现为准，而不是只描述目标态：

应用
版本
变量
用户
用户组 / 权限
单码
心跳 / 在线 / 解绑
黑名单 / 留言

所有 verify 接口统一往下面这类结构收拢：

{
  "status": 200,
  "msg": "成功",
  "data": {}
}

同时统一兼容这些高频字段别名：

appkey / app_key
uname / username
upwd / password
cdkey / card_code
mac / device_id
vid / vname
nonce
timestamp
signature
Authorization: Bearer <token>

一、签名与验证规则

1. 适用范围

除 heartbeat、unbind 这类 token 驱动接口外，大多数 /api/verify/* 接口都要求：

appkey/app_key
timestamp
nonce
signature

同时还会按各接口补充业务字段，例如：

version
uname/username
upwd/password
mac/device_id
cdkey/card_code
vid/vname

2. 签名算法

当前实现使用：

HMAC-SHA256
密钥：应用 app_secret
原始串：${timestamp}${nonce}${payload}

其中 payload 会根据接口不同，由各字段按顺序拼接。

3. 时间窗

timestamp 必须落在 5 分钟有效期内
超时会返回：请求已过期

4. 统一失败风格

失败时返回：

{
  "status": 0,
  "msg": "错误信息",
  "data": ""
}

二、验证平台主接口

1. 软件初始化

路径：POST /api/verify/init
兼容：GET /api/verify/init
用途：初始化软件、返回软件基础信息、当前版本与心跳配置

请求字段：

appkey/app_key
version
timestamp
nonce
signature

签名 payload：

appkey + version

当前返回核心字段：

data.appname
data.appinfo
data.version
data.currentVersion
data.updateurl
data.updatelog
data.forceUpdate
data.heartbeat

2. 用户登录

路径：POST /api/verify/login
用途：账号密码登录、设备绑定、发放 token

请求字段：

appkey/app_key
uname/username
upwd/password
mac/device_id
device_name
timestamp
nonce
signature

签名 payload：

appkey + uname + upwd + mac

当前返回核心字段：

data.token
data.uname
data.finaltime
data.point
data.mac

3. 单码登录

路径：POST /api/verify/card-login
用途：卡密核销、自动创建或续期账号、发放 token

请求字段：

appkey/app_key
cdkey/card_code
mac/device_id
timestamp
nonce
signature

签名 payload：

appkey + cdkey + mac

当前返回核心字段：

data.token
data.uname
data.finaltime
data.point
data.mac

4. 用户状态

路径：POST /api/verify/status
兼容：GET /api/verify/status
用途：查询用户是否封禁、是否绑定、是否在线、是否过期

请求字段：

appkey/app_key
uname/username
mac/device_id（可选但建议传）
timestamp
nonce
signature

签名 payload：

appkey + uname + mac

当前返回核心字段：

data.uname
data.finaltime
data.isbind
data.isonline
data.isban
data.banreason
data.isexpired
data.point

5. 在线心跳

路径：POST /api/verify/heartbeat
用途：维持在线状态，持续校验 token 是否仍有效

请求头：

Authorization: Bearer <token>

当前返回核心字段：

data.uname
data.mac
data.timestamp

6. 用户解绑

路径：POST /api/verify/unbind
用途：释放当前设备绑定，便于换机登录

请求头：

Authorization: Bearer <token>

请求体：

device_id 或 mac
nonce

当前返回核心字段：

data.mac
data.nonce
data.timestamp

三、软件 / 版本 / 变量接口

1. 取软件数据

路径：POST /api/verify/get-app-core
兼容：GET /api/verify/get-app-core
用途：返回软件主体、心跳参数、用户组摘要

请求字段：

appkey/app_key
timestamp
nonce
signature

签名 payload：

appkey

当前返回核心字段：

data.appid
data.appname
data.appinfo
data.heartbeat
data.groups

2. 取版本数据

路径：POST /api/verify/get-ver-core
兼容：GET /api/verify/get-ver-core
用途：返回当前版本、更新地址、更新日志、强更策略

请求字段：

appkey/app_key
timestamp
nonce
signature

签名 payload：

appkey

当前返回核心字段：

data.version
data.updateurl
data.updatelog
data.forceUpdate

3. 取变量数据

路径：POST /api/verify/get-var-core
兼容：GET /api/verify/get-var-core
用途：按变量 ID 或变量名读取远程配置

请求字段：

appkey/app_key
vid 或 vname
timestamp
nonce
signature

签名 payload：

appkey + (vid 或 vname)

当前返回核心字段：

data.vid
data.vname
data.value
data.description

四、用户资料与权限接口

1. 取用户权限

路径：POST /api/verify/get-user-power
兼容：GET /api/verify/get-user-power
用途：聚合用户组与 permissions，作为客户端权限判断基础

请求字段：

appkey/app_key
uname/username
timestamp
nonce
signature

当前返回核心字段：

data.uname
data.point
data.groups
data.permissions

2. 取用户资料

路径：POST /api/verify/get-user-profile
兼容：GET /api/verify/get-user-profile
用途：读取邮箱、手机号、QQ、扩展资料和备注

请求字段：

appkey/app_key
uname/username
timestamp
nonce
signature

当前返回核心字段：

data.uname
data.finaltime
data.point
data.email
data.phone
data.qq
data.data
data.note

3. 设置用户资料

路径：POST /api/verify/set-user-profile
兼容：GET /api/verify/set-user-profile
用途：写入资料字段并回写到用户 metadata

请求字段：

appkey/app_key
uname/username
email
phone
qq
data
note
timestamp
nonce
signature

当前返回核心字段：

data.uname
data.email
data.phone
data.qq
data.data
data.note

五、黑名单与留言接口

1. 软件黑名单

路径：POST /api/verify/set-app-black
用途：按设备和风险类型上报异常，进入风控链路

常见字段：

appkey/app_key
mac
type
note
timestamp
nonce
signature

2. 软件留言

路径：POST /api/verify/set-app-message
用途：客户端提交售后留言、问题反馈和联系方式

常见字段：

appkey/app_key
uname/username
version
contact
message
timestamp
nonce
signature

六、开发者后台接口

下面这些接口用于网站控制台，不是客户端 verify 主链路，但它们已经开始服务同一套平台实体：

1. 开发者认证

POST /api/auth/login
POST /api/auth/register
POST /api/auth/logout
POST /api/auth/change-password
POST /api/auth/reset-password

2. 应用工作台

GET /api/applications
POST /api/applications
GET /api/applications/[id]
PATCH /api/applications/[id]
DELETE /api/applications/[id]
GET /api/applications/[id]/platform
GET /api/applications/[id]/version

3. 变量中心

GET /api/applications/[id]/variables
POST /api/applications/[id]/variables
PUT /api/applications/[id]/variables/[varId]
DELETE /api/applications/[id]/variables/[varId]

4. 应用用户体系

GET /api/applications/[id]/users
POST /api/applications/[id]/users
PATCH /api/applications/[id]/users/[userId]
DELETE /api/applications/[id]/users/[userId]
GET /api/applications/[id]/groups
POST /api/applications/[id]/groups
PUT /api/applications/[id]/groups/[groupId]
DELETE /api/applications/[id]/groups/[groupId]

5. 单码体系

GET /api/applications/[id]/card-types
POST /api/applications/[id]/card-types
PUT /api/applications/[id]/card-types/[typeId]
DELETE /api/applications/[id]/card-types/[typeId]
GET /api/applications/[id]/cards
POST /api/applications/[id]/cards
GET /api/applications/[id]/card-records

七、当前接口边界

目前已经完成的重点，是把：

应用页
版本页
变量页
用户页
用户组页
卡类 / 卡密 / 核销页
/api/verify/* 主链路

收拢为同一套授权平台语义。

但仍有几点需要继续推进：

外层加密封装与完整 SDK 风格还可以继续统一
部分 verify 接口仍在兼容字段别名阶段，尚未沉淀成最终 SDK 协议层
个别后台能力还没有全部折叠进公开验证主链路

也就是说：

现在已经不是普通 SaaS 后台接口文档
也还没有完全停在文档层汇报
后续会继续往“真正的软件授权验证平台”方向收口

API 参考文档

一、签名与验证规则

1. 适用范围

2. 签名算法

3. 时间窗

4. 统一失败风格

二、验证平台主接口

1. 软件初始化

2. 用户登录

3. 单码登录

4. 用户状态

5. 在线心跳

6. 用户解绑

三、软件 / 版本 / 变量接口

1. 取软件数据

2. 取版本数据

3. 取变量数据

四、用户资料与权限接口

1. 取用户权限

2. 取用户资料

3. 设置用户资料

五、黑名单与留言接口

1. 软件黑名单

2. 软件留言

六、开发者后台接口

1. 开发者认证

2. 应用工作台

3. 变量中心

4. 应用用户体系

5. 单码体系

七、当前接口边界

八、相关页面