API 文档 - 授权系统

API 文档

接入说明

基础地址

https://你的域名.com/api

鉴权方式

客户端使用项目的 app_key 调用激活与校验接口。后台管理接口应使用管理员 Token，不放到客户端。

授权码规则

授权码为 20 位，包含大写字母、小写字母、数字与符号。数据库正式版建议保存哈希，不保存明文。

到期控制

到期时间以服务端时间为准。应用启动、关键操作前、定时心跳都应调用校验接口，最长不能超过 1 小时不校验。

客户端流程

推荐接入步骤

用户输入授权码后，应用调用激活接口绑定设备。
激活成功后，本地只保存授权码、设备 ID、最近一次成功校验时间。
每次启动和每隔 10-60 分钟调用校验接口，必须保证至少每 1 小时校验一次。
接口返回 valid: false、项目停用、授权码禁用或过期时，应用停止核心功能。
桌面应用可以允许短时间离线缓存，建议不超过 24-72 小时。

POST /api/licenses/activate

首次使用授权码时调用。未激活授权码会从当前服务端时间开始计算到期时间。

{
  "app_key": "app_xxxxx",
  "license_code": "A8k#9Lm2Qp@7Zx5Rt1B",
  "device_id": "device_unique_id",
  "device_name": "Windows-PC"
}

{
  "valid": true,
  "status": "active",
  "license_id": "lic_001",
  "project_id": "proj_001",
  "expires_at": "2026-08-03T12:00:00.000Z",
  "remaining_seconds": 2592000,
  "check_interval_seconds": 3600,
  "next_verify_at": "2026-07-04T13:00:00.000Z",
  "server_time": "2026-07-04T12:00:00.000Z"
}

POST /api/licenses/verify

应用启动、定时心跳、进入核心功能前调用。到期后返回不可用。

{
  "app_key": "app_xxxxx",
  "license_code": "A8k#9Lm2Qp@7Zx5Rt1B",
  "device_id": "device_unique_id"
}

{
  "valid": true,
  "status": "active",
  "expires_at": "2026-08-03T12:00:00.000Z",
  "remaining_seconds": 2592000,
  "check_interval_seconds": 3600,
  "next_verify_at": "2026-07-04T13:00:00.000Z",
  "server_time": "2026-07-04T12:00:00.000Z"
}

错误码

常见失败原因

license_not_found授权码不存在，或不属于当前项目。

license_not_activated授权码还没有激活，需先调用激活接口。

license_expired授权已到期，客户端应停止使用。

license_disabled授权码被后台禁用。

device_limit_exceeded绑定设备数量超过上限。

device_not_bound当前设备没有绑定该授权。

project_disabled_or_not_found项目不存在或已停用。