开发文档 - AegisAuthnb

API 概览

AegisAuthnb API 遵循最小权限原则，仅对外暴露卡密验证与云更新两类核心功能。所有接口通过 HTTPS 通信，返回标准 JSON 格式数据，并经完整中间件链路保障安全。

基础地址

/api

所有 API 请求的基础 URL，请替换为实际部署域名，生产环境请使用 HTTPS。

认证方式

app_key(ak_ 前缀) + app_secret(sk_ 前缀) + API Key(dk_ 前缀) + Cookie(会话) + RSA-4096-OAEP 非对称签名 + HMAC-SHA384 消息认证 + 时间戳/nonce 防重放

完整认证链：app_key（ak_ 前缀）标识应用；app_secret（sk_ 前缀）校验应用归属；API Key（dk_ 前缀）双重校验；Cookie 维持会话；RSA-4096-OAEP 非对称加密 + HMAC-SHA384 对请求体签名（sign 字段）；timestamp/nonce 防重放。由 AppAuthMiddleware、HandshakeMiddleware、DecryptMiddleware 依次校验。

速率限制

4 维度限流

RateLimitMiddleware 提供 4 维度限流（IP/app_key/device_id/user），超限返回 1005 错误码。

API 版本

v1

当前 API 版本为 v1，路由统一以 /api 前缀暴露，版本信息体现在响应与文档中。

内容类型

application/json

所有请求与响应均使用 application/json 格式。

卡密验证

卡密验证接口用于校验卡密合法性、维护在线会话与设备绑定，建立会话后凭 session_id 维持授权状态。device_sign 由客户端使用 app_secret 计算 HMAC-SHA384，用于防止 device_id 伪造。

POST /api/auth/card/verify

卡密验证，校验 device_sign 并自动绑定设备

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
card_key	string	必填	卡密码
device_id	string	必填	设备唯一标识
device_sign	string	必填	设备签名 HMAC-SHA384(device_id, app_secret)

请求示例

curl -X POST /api/auth/card/verify \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","card_key":"AGS-XXXX-XXXX-XXXX","device_id":"device-001","device_sign":"hmac-sha384-hex"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "statecode": 0,
    "message": "验证成功",
    "card_id": 2001,
    "expire_at": "2026-02-14 10:30:00",
    "validity": 30,
    "remaining": 30,
    "session_id": "sess-xxxxxxxx"
  }
}

POST /api/auth/card/heartbeat

卡密心跳，续期授权并更新在线设备状态

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
card_key	string	必填	卡密码
device_id	string	必填	设备唯一标识

请求示例

curl -X POST /api/auth/card/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","card_key":"AGS-XXXX-XXXX-XXXX","device_id":"device-001"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "statecode": 0,
    "message": "ok",
    "expire_at": "2026-02-14 10:30:00",
    "server_time": 1736932200
  }
}

POST /api/auth/card/logout

卡密登出，解绑当前设备并销毁卡密会话

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
card_key	string	必填	卡密码
device_id	string	必填	设备唯一标识

请求示例

curl -X POST /api/auth/card/logout \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","card_key":"AGS-XXXX-XXXX-XXXX","device_id":"device-001"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "statecode": 0,
    "message": "卡密登出成功"
  }
}

POST /api/auth/card/transfer

卡密转卡，将当前卡密余额转移到目标卡密

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
card_key	string	必填	原卡密码
target_card_key	string	必填	目标卡密码（接收余额的新卡密）
device_id	string	必填	设备唯一标识

请求示例

curl -X POST /api/auth/card/transfer \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","card_key":"AGS-XXXX-XXXX-XXXX","target_card_key":"AGS-YYYY-YYYY-YYYY","device_id":"device-001"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "statecode": 0,
    "message": "转卡成功",
    "new_card_key": "AGS-YYYY-YYYY-YYYY"
  }
}

云更新

云更新接口提供版本检查、下载地址获取、进度上报与结果上报能力，服务端基于 device_id 进行灰度判定与统计。

POST /api/app/update/check

云更新检查，基于设备 ID 灰度判定，返回全量包或差量包信息

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
device_id	string	必填	设备唯一标识（用于灰度判定）
current_version	string	必填	客户端当前版本号
client_type	string	选填	客户端类型，如 windows/android/ios
channel	string	选填	发布渠道，如 stable/beta（可选）

请求示例

curl -X POST /api/app/update/check \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","device_id":"device-001","current_version":"1.0.0","client_type":"windows","channel":"stable"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "has_update": true,
    "current_version": "1.0.0",
    "latest_version": "1.1.0",
    "version_name": "1.1.0 正式版",
    "update_type": "full",
    "force_update": false,
    "min_version": "1.0.0",
    "publish_at": "2026-01-10 10:00:00",
    "file_size": 5242880,
    "file_hash": "sha256:abcdef...",
    "description": "修复若干问题并优化性能"
  }
}

POST /api/app/update/download

云更新包下载，返回下载地址与校验信息

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
device_id	string	必填	设备唯一标识
package_id	integer	必填	更新包 ID（由 update/check 返回）
client_type	string	选填	客户端类型：windows/linux/mac/android/ios/web

请求示例

curl -X POST /api/app/update/download \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","device_id":"device-001","package_id":1001,"client_type":"windows"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "download_url": "https://cdn.example.com/update/1.1.0/full.zip?sig=xxx&expires=1736935800",
    "signature": "hmac-sha256:abcdef...",
    "expires_at": 1736935800,
    "file_size": 5242880,
    "file_hash": "sha256:abcdef..."
  }
}

POST /api/app/update/progress

客户端上报下载进度，用于服务端统计与断点续传

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
device_id	string	必填	设备唯一标识
update_id	integer	必填	更新任务 ID（由 update/check 返回）
progress	integer	必填	下载进度百分比（0-100）
speed	integer	选填	下载速度（KB/s）

请求示例

curl -X POST /api/app/update/progress \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","device_id":"device-001","update_id":2001,"progress":65,"speed":102400}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "received": true,
    "server_time": 1736932200
  }
}

POST /api/app/update/report

客户端上报更新结果（成功/失败），用于服务端统计与失败排查

请求参数

参数名	类型	必填	说明
app_key	string	必填	应用密钥
device_id	string	必填	设备唯一标识
update_id	integer	必填	更新任务 ID
status	string	必填	更新状态：success/failed
error_code	integer	选填	失败错误码（status=failed 时必填）

请求示例

curl -X POST /api/app/update/report \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_your_app_key","device_id":"device-001","update_id":2001,"status":"success"}'

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "received": true,
    "server_time": 1736932200
  }
}

错误码

以下是 API 返回的常见错误码及其含义，便于排查问题。错误码与 app/common/enums/ErrorCode.php 枚举对齐。

错误码	错误信息	描述
0	成功	请求成功
1001	请求参数错误	请求参数缺失或格式错误
1002	未授权（token无效/过期/缺失）	未授权：访问令牌无效、过期或缺失
1003	权限不足/IP被封禁	权限不足或 IP 已被封禁
1004	资源不存在	请求的资源不存在
1005	请求过于频繁	请求过于频繁，触发 4 维度限流
1006	服务器内部错误	服务器内部错误，请稍后重试
1007	应用不存在或已禁用	应用不存在或已禁用
1008	应用维护中	应用处于维护中
1009	签名验证失败	HMAC-SHA384 签名验证失败
1010	时间戳过期	请求时间戳过期（防重放）
1011	nonce重复	nonce 重复（防重放）
1013	解密失败	请求体解密失败
1014	客户端版本过低	客户端版本过低，请升级后重试
2001	卡密无效	卡密无效（状态异常，如已冻结）
2002	卡密已作废	卡密已作废
2003	卡密已过期	卡密已过期
2004	卡密不存在	卡密不存在（该应用下未找到此卡密）
2005	卡密已被使用	卡密已被使用（单次卡/次数卡用完）
2009	卡密验证失败次数超限	卡密验证失败次数超限（暴力破解保护）
4001	权益不足	权益不足（会员等级不够或功能未解锁）
4002	会员已到期	会员已到期
7001	无可用更新	无可用更新
7002	更新下载失败	更新包下载失败
7003	更新文件完整性校验失败	更新文件完整性校验失败
7004	更新文件解密/解压失败	更新文件解密或解压失败
9001	设备数已达上限	设备数已达上限
9002	设备未绑定	设备未绑定
9003	设备在黑名单中	设备已在黑名单中

AegisAuthnb 开发文档

请求参数

请求参数

请求参数

请求参数

请求参数

请求参数

请求参数

请求参数