云授权 · 网络验证平台 · 开发者文档

Open API 调用文档

所有接口均使用 app_id 标识应用；受控权益与资源接口还会校验登录后取得的 Bearer Token。

Base URL

https://api.xxauth.com

认证方式

所有 Open API 接口均需请求头 app_id。动态权益接口通过卡密登录或门户用户登录返回的 access_token 校验具体账号权限。

访问受控资源时增加 Authorization: Bearer <access_token>。访问令牌有效期 2 小时并绑定应用和账号；公开资源只需要 app_id。

GET /open/v1/announcements HTTP/1.1
Host: api.xxauth.com
app_id: your_app_id_here

# 受控权益接口额外携带
Authorization: Bearer your_access_token

软件启用 OpenAPI 请求签名后，还必须按配置携带 X-Timestamp、X-Nonce 与 X-Signature；时间戳偏移和 nonce 重放会被拒绝。启用 OpenAPI 加密中间件时，请求与响应还会按软件安全配置加解密。

响应防重放

开发者在「软件详情 → 安全配置 → 重放攻击检测」开启响应防重放后，每个响应都会绑定本次请求的时间戳和 nonce，使用一次性派生密钥加密，并对原始密文附加 HMAC-SHA256 签名。该开关默认关闭；开启前必须先配置对称加密算法和加密密钥。

响应头说明
X-Response-Protection固定为 replay-v1
X-Request-Timestamp原样回显本次请求的 X-Timestamp，仅用于比对
X-Request-Nonce原样回显本次请求的 X-Nonce，仅用于比对
X-Response-Timestamp服务端生成响应时的 Unix 秒
X-Response-Nonce服务端为本次响应生成的 16 字节随机 nonce（小写 hex）
X-Response-Signature标准 Base64 编码的 HMAC-SHA256 响应签名

派生和验签均使用软件安全配置中的原始encrypt_key作为 HMAC 密钥。所有字符串按 UTF-8 编码，换行固定为 LF（\n），HTTP 方法转为大写，PATH 不含 query，HTTP 状态码使用十进制。

binding =
  "replay-v1" + "\n" +
  app_id + "\n" +
  UPPERCASE(http_method) + "\n" +
  request_path_without_query + "\n" +
  request_timestamp + "\n" +
  request_nonce + "\n" +
  response_timestamp + "\n" +
  response_nonce

response_key = HMAC_SHA256(base_encrypt_key, UTF8(binding))

signature_input =
  binding + "\n" +
  decimal_http_status + "\n" +
  HEX_LOWER(SHA256(raw_ciphertext))

expected_signature = BASE64_STD(
  HMAC_SHA256(base_encrypt_key, UTF8(signature_input))
)

response_key是 HMAC 的原始 32 字节结果，不是 hex 或 Base64 字符串。加密算法沿用服务端现有密钥取法：AES-128 取前 16 字节、AES-192 取前 24 字节、AES-256 与 ChaCha20-Poly1305 取全部 32 字节、SM4 取前 16 字节、DES 取前 8 字节、3DES 取前 24 字节；Blowfish 与 RC4 使用全部 32 字节。

客户端处理顺序

  1. 在本地保存刚发送的 X-Timestamp、X-Nonce、APPID、方法和路径；每次请求必须生成新的 nonce。
  2. 检查 X-Response-Protection，并确认响应头中的 X-Request-Timestamp、X-Request-Nonce 与本地保存值完全相同。不能使用响应头中的请求值替代本地值参与计算。
  3. 如存在 X-Encoded，先按指定编码还原出 raw_ciphertext，再用原始加密密钥计算响应签名，并使用恒定时间比较。
  4. 签名通过后派生 response_key，按软件配置的对称算法解密 raw_ciphertext；不能继续用原始加密密钥直接解密响应。
  5. JSON 响应还会在顶层包含 _response_security，必须再次核对全部关联字段；二进制响应只通过已签名的响应头完成关联校验。
  6. 校验响应时间戳的新鲜度，并在客户端请求生命周期内拒绝重复消费同一个 response_nonce。任一步失败都丢弃响应。
{
  "code": 0,
  "message": "success",
  "data": {},
  "_response_security": {
    "version": "replay-v1",
    "app_id": "your_app_id_here",
    "method": "POST",
    "path": "/open/v1/card/login",
    "request_timestamp": "1786310400",
    "request_nonce": "client-random-nonce",
    "response_timestamp": "1786310401",
    "response_nonce": "b7a4c2f19d8e6a305142779fbe22dd01"
  }
}

协议适配（兼容其他平台）

默认响应统一为 { "code": 0, "message": "success", "data": {...} }， 成功时 code=0。

如需从其他网络验证平台迁移，可在「软件详情 → 协议适配」中开启并自定义：外层字段名（code/message/data 改名）、 成功码 / 失败码值、请求字段名映射（客户端字段名 → 平台真实字段名）、响应字段名映射（平台字段名 → 输出字段名）。 开启后下文所有接口的请求/响应字段会按你的配置自动改写，无需改动接口路径，客户端几乎零改造即可对接。 也可直接套用平台内置或共享的兼容预设。

// 示例：把成功码改为 200、外层字段改名、机器码字段改名
// 配置：success_code=200, field_code=status, field_data=result,
//      resp_field_map={"bound_machine_code":"machine"}
{ "status": 200, "message": "success", "result": { "machine": "ABC123" } }

基础接口

2 个接口
GET/open/v1/init初始化（聚合接口）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
platformquerystring否平台（windows/mac/android/ios），默认 windows
card_noheaderstring否卡密号（开启 variables_auth_required 时拉变量需要）
user_idheaderstring否用户ID（同上，与 card_no 二选一）
X-Anon-IDheaderstring否匿名设备ID（free模式首次 init 获取后缓存，后续请求携带）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "software": {
      "id": "sw_xxxx",
      "name": "我的软件",
      "icon": "https://cdn/icon.png",
      "pricing_mode": "paid"
    },
    "auth": {
      "login_mode": "user",
      "register_enabled": "true"
    },
    "limit": {
      "max_devices": 3,
      "max_online": 1
    },
    "update": {
      "default_strategy": "optional",
      "update_notice": ""
    },
    "status_codes": {
      "card_expired": "1001"
    },
    "variables": {
      "max_devices": "3"
    },
    "security": {
      "anti_debug": false,
      "heartbeat_interval": 60,
      "heartbeat_timeout": 180,
      "heartbeat_verify_machine": false,
      "heartbeat_verify_ip": false,
      "encrypt_algorithm": "aes-cbc"
    },
    "announcements": [
      {
        "id": "ann_xxxx",
        "title": "公告标题",
        "content": "公告内容"
      }
    ],
    "latest_version": {
      "version": "1.2.0",
      "download_url": "https://example.com/app-1.2.0.exe"
    },
    "pricing_mode": "paid",
    "anon_id": ""
  }
}
GET/open/v1/config/:category按分类获取配置

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
categorypathstring是配置分类（auth/limit/update/status_code/variable）；security 与 agent 受保护，不可访问
card_noheaderstring否拉 variable 分类时受 variables_auth_required 控制是否必填
user_idheaderstring否同上，可与 card_no 二选一

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "max_devices": "3",
    "max_online": "1"
  }
}

卡密验证 API

7 个接口
POST/open/v1/card/login单码卡密登录

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_nobodystring是卡密号
machine_codebodystring否机器码
timestampbodystring否时间戳

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "card_id": "crd_xxxx",
    "card_no": "XXXX-XXXX-XXXX",
    "expires_at": "2026-04-17T00:00:00Z",
    "bound_ip": "1.2.3.4",
    "bound_machine_code": "ABC123",
    "software_id": "sw_xxxx",
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}
POST/open/v1/card/deduct点卡主动扣点

仅用于点卡。count 不传或小于等于 0 时按 1 点扣除；开启机器码/IP 绑定后会同时校验绑定信息。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_nobodystring是点卡卡号
countbodyinteger否扣除点数，默认 1
machine_codebodystring否开启机器码绑定时必填

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "card_no": "XXXX-XXXX-XXXX",
    "deducted": 1,
    "points": 99,
    "remaining": 99
  }
}
POST/open/v1/card/heartbeat单码卡密心跳验证

卡密登录成功后应按 /open/v1/init 返回的 security.heartbeat_interval 持续调用。只有连续未上报时间达到独立配置的 security.heartbeat_timeout 后，卡密信息、扣点、变量、云配置、权益资源和云逻辑等受保护接口才会返回 401；heartbeat_timeout 默认 90 秒，由开发者按客户端实际频率设置。max_online 与用户名登录共享当前软件的在线额度，0 表示不限制。超时后的心跳不能恢复会话，必须重新登录。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_nobodystring是卡密号
machine_codebodystring否机器码。当软件「安全配置」开启『心跳校验机器码』时必填，且需与激活时绑定的机器码一致，否则心跳被拒绝

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": true,
    "expires_at": "2026-04-17T00:00:00Z",
    "remaining_seconds": 86400
  }
}
GET/open/v1/card/info获取单码卡密信息

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noquerystring是卡密号

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "card_no": "XXXX-XXXX-XXXX",
    "status": 1,
    "expires_at": "2026-04-17T00:00:00Z",
    "bound_ip": "1.2.3.4",
    "bound_machine_code": "ABC123",
    "duration": 720,
    "created_at": "2026-01-01T00:00:00Z"
  }
}
GET/open/v1/card/check卡密状态检查（轻量级）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noquerystring是卡密号

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": true,
    "status": 1,
    "status_text": "已使用"
  }
}
POST/open/v1/card/unbind-device解绑机器码

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_nobodystring是卡密号
machine_codebodystring否仅当 unbind.unbind_verify_machine 开启时必填，且必须匹配该卡密当前绑定的机器码

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}
POST/open/v1/card/unbind-ip解绑IP

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_nobodystring是卡密号

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}

用户验证 API

11 个接口
POST/open/v1/user/send-email-code发送邮箱验证码（注册/登录/修改密码）

当软件「验证配置」开启对应邮箱验证开关时，在注册、登录或修改密码前先用本接口获取验证码。 register 场景：传 email，验证码发送到该邮箱； login 场景：传 username，后端据此查出账号绑定的邮箱再发送。 change_password 场景：传 user（软件内门户用户名），验证码只会发送到该账号已登记的邮箱，不接受调用方指定收件邮箱。 是否需要验证码由对应软件的验证配置开关决定，与平台全局邮箱验证开关无关。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
scenebodystring是场景：register（注册）、login（登录）或 change_password（修改密码）
emailbodystring否register 场景必填，接收验证码的邮箱
usernamebodystring否login 场景必填；change_password 场景建议使用 user 字段
userbodystring否change_password 场景必填，填写当前软件内的门户用户名

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}
POST/open/v1/user/register用户注册

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
usernamebodystring是用户名
passwordbodystring是密码
nicknamebodystring否昵称
emailbodystring否邮箱。当软件「安全配置」开启『注册邮箱验证』时必填
email_codebodystring否邮箱验证码。开启『注册邮箱验证』时必填，先调用 /open/v1/user/send-email-code 获取
captcha_tokenbodystring否图形验证码 token。开启『验证码』时必填
captcha_valuebodystring否图形验证码值。开启『验证码』时必填

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": "usr_xxxx",
    "username": "test",
    "nickname": "test",
    "vip_level": 1,
    "vip_expire_at": "2026-05-01T00:00:00Z"
  }
}
POST/open/v1/user/login用户登录

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
usernamebodystring是用户名
passwordbodystring是密码
machine_codebodystring否机器码。当软件「安全配置」开启『绑定机器码』时必填。支持多设备绑定：由 limit.max_devices 控制当前软件下每个用户的上限，0 表示不限制；关闭绑定机器码时该限制不生效。同一软件下机器码不能归属多个用户。
email_codebodystring否邮箱验证码。当软件「安全配置」开启『登录邮箱验证』时必填，先调用 /open/v1/user/send-email-code 获取（发送到账号绑定邮箱）
captcha_tokenbodystring否图形验证码 token。开启『验证码』时必填
captcha_valuebodystring否图形验证码值。开启『验证码』时必填

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": "usr_xxxx",
    "username": "test",
    "nickname": "test",
    "vip_level": 1,
    "vip_expire_at": "2026-05-01T00:00:00Z",
    "balance": 0,
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}
POST/open/v1/user/recharge用户充值（卡密充值）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
user_idbodystring否用户ID；与 username + password 二选一
usernamebodystring否用户名；账号授权已到期、无法重新登录时可与 password 一起用于续费
passwordbodystring否账号密码；与 username 配套
card_nobodystring是充值卡密

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "充值成功",
    "added_hours": 720,
    "new_vip_expire_at": "2026-05-01T00:00:00Z"
  }
}
POST/open/v1/user/heartbeat用户心跳验证

登录成功后应按 /open/v1/init 返回的 security.heartbeat_interval 持续调用。只有连续未上报时间达到独立配置的 security.heartbeat_timeout 后，用户信息、变量、云配置、权益资源和云逻辑等受保护接口才会返回 401；heartbeat_timeout 默认 90 秒，由开发者按客户端实际频率设置。max_online 与卡密登录共享当前软件的在线额度，0 表示不限制。超时后的心跳不能恢复会话，必须重新登录。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
userbodystring是软件内门户用户名；旧版 user_id 仍兼容但不再推荐
machine_codebodystring否机器码。当软件「安全配置」开启『心跳校验机器码』时必填，需为登录时绑定的任一设备码（查 user_devices 表），未绑定或已解绑则心跳被拒绝

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": true
  }
}
POST/open/v1/user/logout用户注销

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
userbodystring是软件内门户用户名；无需先登录获取用户ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}
DELETE/portal/:slug/devices/:deviceId门户逐台解绑设备（需验证当前密码）

必须携带 X-Portal-User-ID，且该用户属于当前门户对应的软件。请求体必须提供当前账号 password；仅能删除当前用户在当前软件下的指定设备，不能跨账号或跨软件解绑。

请求示例

{
  "password": "当前密码"
}

请求参数

参数名位置类型必填说明
slugpathstring是门户标识
deviceIdpathuuid是设备记录ID
X-Portal-User-IDheaderuuid是当前门户用户ID
passwordbodystring是当前门户账号密码

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}
POST/open/v1/user/unbind-device用户解绑机器码（需校验密码，按 unbind 配置可能扣费/扣时长）

解绑当前用户的所有已绑定设备（清空 user_devices 表 + 重置 BoundMachineCode）。 如需逐台解绑，请使用门户端 /portal/:slug/devices/:deviceId 接口。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
userbodystring是软件内门户用户名；无需先登录获取用户ID
passwordbodystring是账户密码（必须）
machine_codebodystring否仅当 unbind.unbind_verify_machine 开启时必填，且必须是该账号当前已绑定的机器码

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "deducted_fee_cent": 0,
    "deducted_hours": 0,
    "balance": 1500,
    "vip_expire_at": "2026-05-01T00:00:00Z",
    "devices_removed": 1,
    "remaining_devices": 0
  }
}
POST/open/v1/user/unbind-ip用户解绑IP

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
userbodystring是软件内门户用户名；无需先登录获取用户ID
passwordbodystring是账户密码（必须）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "deducted_fee_cent": 0,
    "deducted_hours": 0,
    "balance": 1500,
    "vip_expire_at": "2026-05-01T00:00:00Z"
  }
}
GET/open/v1/user/info获取用户信息

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
user_idquerystring是用户ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "usr_xxxx",
    "username": "test",
    "nickname": "test",
    "vip_level": 1,
    "vip_expire_at": "2026-05-01T00:00:00Z",
    "balance": 0,
    "last_login_ip": "1.2.3.4",
    "created_at": "2026-01-01T00:00:00Z"
  }
}
POST/open/v1/user/change-password用户修改密码

开发者通过软件「验证配置」的 change_password_verify_mode 选择验证旧密码（old_password）或验证注册邮箱（email），两种方式二选一。旧版 change_password_verify_email=true 自动兼容为 email。 邮箱模式不需要 old_password；验证码需先调用 /open/v1/user/send-email-code 获取：scene=change_password，并传相同账号的 user。验证码仅在密码修改成功后消耗。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
userbodystring是软件内门户用户名；无需先登录获取用户ID
old_passwordbodystring否旧密码。change_password_verify_mode=old_password 时必填
new_passwordbodystring是新密码
email_codebodystring否注册邮箱验证码。change_password_verify_mode=email 时必填

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}

访问名单 API

1 个接口
POST/open/v1/security/ban-current拉黑当前连接 IP 与机器码

无需填写账号。服务端按 app_id 将当前请求的真实连接 IP 和机器码同时加入该软件的黑名单，两个值在同一事务中写入，仅对当前软件生效。IP 固定取服务端连接信息，客户端不能传入或覆盖。机器码可放在 JSON 的 machine_code 字段或 X-Machine-Code 请求头中。生产环境建议开启 api_sign_verify，避免接口被未授权调用。

请求示例

curl -X POST "https://你的API域名/open/v1/security/ban-current" \
  -H "Content-Type: application/json" \
  -H "app_id: 你的APPID" \
  -d '{"machine_code":"当前设备机器码","remark":"客户端主动封禁"}'

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID；也兼容现有 OpenAPI 的 app_id 查询参数
machine_codebodystring否当前设备机器码；与 X-Machine-Code 二选一，最大 256 个字符
X-Machine-Codeheaderstring否当前设备机器码；与 body.machine_code 二选一
remarkbodystring否拉黑备注，最大 500 个字符

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ip": "203.0.113.7",
    "machine_code": "DEVICE-001",
    "blocked": true
  }
}

软件信息 API

8 个接口
GET/open/v1/announcements获取程序公告

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "ann_xxxx",
      "title": "公告标题",
      "content": "公告内容",
      "priority": 1,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}
GET/open/v1/articles获取文章

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "art_xxxx",
      "title": "文章标题",
      "summary": "摘要",
      "content": "内容",
      "category": "教程",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}
GET/open/v1/banners获取启动页 Banner 列表

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "bnr_xxxx",
      "image": "https://cdn/banner.png",
      "link": "https://...",
      "title": "活动标题",
      "sort_order": 0
    }
  ]
}
GET/open/v1/version/latest获取最新版本号

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
platformquerystring否平台，默认 windows

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "version": "1.2.0",
    "download_url": "https://example.com/app-1.2.0.exe",
    "change_log": "修复了若干问题",
    "file_size": 10485760,
    "platform": "windows"
  }
}
POST/open/v1/version/check检测当前是否为最新版本（支持灰度/强制更新/通道）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
versionbodystring是当前版本号
platformbodystring否平台，默认 windows
channelbodystring否更新通道：stable/beta/alpha，默认 stable
device_idbodystring否设备稳定标识，用于灰度命中计算

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "is_latest": false,
    "latest_version": "1.2.0",
    "download_url": "https://example.com/app-1.2.0.exe",
    "change_log": "修复了若干问题",
    "update_strategy": "optional",
    "force_update": false,
    "channel": "stable",
    "published_at": "2026-01-01T00:00:00Z",
    "rollout_percent": 100,
    "file_size": 10485760,
    "file_hash": "sha256:xxxxxx",
    "update_notice": "升级提示文案"
  }
}
GET/open/v1/version/list版本列表（按 published_at 倒序）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
platformquerystring否平台过滤，留空返回所有平台

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "ver_xxxx",
      "version": "1.2.0",
      "platform": "windows",
      "channel": "stable",
      "status": 1,
      "push_enabled": true,
      "download_url": "https://...",
      "change_log": "...",
      "file_size": 10485760,
      "published_at": "2026-01-01T00:00:00Z"
    }
  ]
}
GET/open/v1/variables获取程序变量

返回软件「配置管理 → 程序变量」中定义的所有键值对。 受软件「安全配置 → 获取变量需要验证」开关（variables_auth_required）控制： 关闭时所有请求方均可直接拉取；开启时必须携带合法的 card_no 或 user_id。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（variables_auth_required 开启时必填，与 user_id 二选一）
user_idheaderstring否用户ID（variables_auth_required 开启时必填，与 card_no 二选一）

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "key": "max_devices",
      "value": "3",
      "remark": "最大设备数"
    }
  ]
}
POST/open/v1/variable/:key按名称获取单个程序变量

仅返回 key 匹配的单个变量。 权限控制与 /variables 一致：variables_auth_required 决定是否需要身份校验。 变量不存在时返回 404。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
keypathstring是变量名称
card_noheaderstring否卡密号（variables_auth_required 开启时必填）
user_idheaderstring否用户ID（variables_auth_required 开启时必填）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "key": "max_devices",
    "value": "3"
  }
}

动态权益与受控资源 API

5 个接口
GET/open/v1/entitlements/me查询当前账号的权限与会员

先调用卡密登录或门户用户登录获取 access_token。令牌有效期为 2 小时，并绑定当前 app_id 与登录主体。权限和会员各自独立到期；expires_at 不返回时表示无期限。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
Authorizationheaderstring是Bearer <access_token>

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "subject_type": "portal_user",
    "permissions": [
      {
        "permission_id": "perm_xxxx",
        "code": "game_a",
        "name": "游戏A权限",
        "expires_at": "2026-09-08T12:00:00Z"
      }
    ],
    "memberships": [
      {
        "membership_id": "member_xxxx",
        "code": "svip",
        "name": "SVIP",
        "access_all_files": true,
        "expires_at": "2027-08-08T12:00:00Z"
      }
    ]
  }
}
GET/open/v1/entitlements/resources列出当前可访问的资源

未登录时仅返回公开资源；携带有效 Bearer Token 时，还会返回当前账号有权访问的受控资源，无权资源不会出现在列表中。一个权限可关联多个资源；一个资源也可绑定多个权限，并由后台配置 any（满足任一）或 all（全部满足）。资源类型支持 text、json、link、file。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
Authorizationheaderstring否Bearer <access_token>；只读取公开资源时可不传

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "res_xxxx",
      "code": "game_a_script",
      "name": "游戏A脚本",
      "description": "Lua 主脚本",
      "resource_type": "file",
      "is_public": false,
      "file_name": "game_a.lua",
      "file_size": 23841
    }
  ]
}
GET/open/v1/entitlements/resources/:code/checksum获取文件资源校验和

供开发者集成的客户端在更新权益资源前做本地缓存校验。公开文件可匿名查询；受控文件必须携带有效 Bearer Token。返回 SHA-256、MD5、文件大小和文件名；哈希一致时无需再次下载，不一致时再调用资源接口获取一次性下载凭证。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
Authorizationheaderstring否Bearer <access_token>；受控资源必填
codepathstring是开发者配置的文件资源编码

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "code": "game_a_script",
    "type": "file",
    "file_name": "game_a.lua",
    "file_size": 23841,
    "sha256": "a3f5...",
    "md5": "9e107d9d372bb6826bd81d3542a419d6"
  }
}
GET/open/v1/entitlements/resources/:code按编码获取资源内容或下载凭证

公开资源无需登录；受控资源必须携带 Bearer Token，后端实时校验权限。text/json/link 直接在 value 返回内容；file 只返回短期 download_url，不返回磁盘路径、对象存储键或文件哈希。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
Authorizationheaderstring否Bearer <access_token>；受控资源必填
codepathstring是开发者配置的资源编码

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "code": "game_a_script",
    "type": "file",
    "download_url": "/open/v1/entitlements/download/eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 120,
    "file_name": "game_a.lua",
    "file_size": 23841
  }
}
GET/open/v1/entitlements/download/:ticket下载受控文件（二进制）

download_url 仅 2 分钟有效且只能成功消费一次。下载前后端会再次校验资源和权限；成功响应为文件原始二进制，错误响应才是 JSON。请勿缓存、复用或拼接该地址。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
ticketpathstring是上一步返回的一次性下载凭证

响应示例

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="download"; filename*=UTF-8''game_a.lua
Cache-Control: private, no-store

<原始文件二进制数据>

应用验证 API

1 个接口
POST/open/v1/app/verify-sign应用签名对比

支持单条 sign + label，也支持 signs 数组批量校验；两种形式至少提供一种。批量调用返回总结果 valid 与逐项 results。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
signbodystring否单条签名值
labelbodystring否单条签名标签
signsbodyarray否批量签名项 [{ label, hash }]

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": true,
    "results": [
      {
        "label": "main.exe",
        "valid": true,
        "remark": "主程序"
      }
    ]
  }
}

在线统计 API

2 个接口
GET/open/v1/stats/online-cards获取在线卡密数量

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "count": 42
  }
}
GET/open/v1/stats/online-users获取在线用户数量

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "count": 128
  }
}

加密工具 API

4 个接口
GET/open/v1/crypto/algorithms列出当前后端支持的加密 / 哈希算法

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "cipher": [
      "aes-cbc",
      "aes-gcm",
      "sm4-cbc"
    ],
    "hash": [
      "md5",
      "sha1",
      "sha256",
      "sha512",
      "sm3"
    ]
  }
}
POST/open/v1/crypto/encrypt对数据加密（Base64 输出）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
databodystring是待加密原文（UTF-8）
algorithmbodystring否算法名；留空走软件 security.encrypt_algorithm 配置
keybodystring否密钥；留空走软件 security.encrypt_key 配置

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "algorithm": "aes-cbc",
    "result": "U2FsdGVkX1+..."
  }
}
POST/open/v1/crypto/decrypt对密文解密

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
databodystring是待解密密文（Base64）
algorithmbodystring否算法名；留空走软件 security 配置
keybodystring否密钥；留空走软件 security 配置

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "algorithm": "aes-cbc",
    "result": "原文字符串"
  }
}
POST/open/v1/crypto/hash计算数据哈希（十六进制输出）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
databodystring是待哈希数据
algorithmbodystring是哈希算法（md5/sha1/sha256/sha512/sm3）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "algorithm": "sha256",
    "result": "e3b0c44298..."
  }
}

云逻辑 API

1 个接口
POST/open/v1/execute按函数名执行云逻辑脚本

受保护接口，必须提供已登录且心跳未超时的 card_no 或 user_id。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_nobodystring否已登录卡密（与 user_id 二选一，也可放在 X-Card-No Header）
user_idbodystring否登录返回的用户ID（与 card_no 二选一，也可放在 X-User-ID Header）
functionbodystring是云逻辑函数名（在开发者后台 → 软件 → 云逻辑中预定义）
paramsbodyobject否传给函数的参数键值对

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "function": "calcLicense",
    "output": "abc123",
    "error": "",
    "time_ms": 12
  }
}

加密传输 API

1 个接口
POST/open/v1/secure代理转发已加密的内部请求

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
encryptedbodystring是Base64(密文(JSON{path, method, body, params}))

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "encrypted": "Base64(密文(原 OpenAPI 响应))"
  }
}

云配置 API

9 个接口
GET/open/v1/cloud-configs/pools列出本软件下所有启用的配置池

受软件「安全配置 → 云配置读取需要验证」开关（cloud_config_auth_required）控制： 关闭时所有请求方均可匿名拉取；开启时必须携带合法的 card_no 或 user_id。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（cloud_config_auth_required 开启时必填，与 user_id 二选一）
user_idheaderstring否用户ID（cloud_config_auth_required 开启时必填，与 card_no 二选一）

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "pool_xxxx",
      "name": "默认规则池",
      "description": "保存核心规则",
      "max_configs_per_user": 10,
      "max_content_size": 102400,
      "allow_share_password": true,
      "allow_share_limit": true
    }
  ]
}
GET/open/v1/cloud-configs/pools/:pid/mine列出当前 card/user 名下的私人配置（分页）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（与 user_id 二选一）
user_idheaderstring否用户ID
pidpathuuid是池 ID
pagequeryint否页码，默认 1
page_sizequeryint否每页数量，默认 20

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "cfg_xxxx",
        "title": "我的私人配置",
        "content": "{...}",
        "status": 1,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
GET/open/v1/cloud-configs/configs/:cid获取单条配置（含内容）

获取某条配置的完整内容。官方推荐配置不需要鉴权； 私人配置需要提供对应卡密/用户的 card_no 或 user_id。 受软件「安全配置 → 云配置读取需要验证」开关（cloud_config_auth_required）控制： 开启时即使读官方推荐也需校验身份。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（访问私人配置时必填；cloud_config_auth_required 开启时读任意配置均必填）
user_idheaderstring否用户ID（同上，与 card_no 二选一）
cidpathuuid是配置 ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "cfg_xxxx",
    "title": "配置标题",
    "content": "{...}",
    "owner_type": "user",
    "owner_id": "usr_xxxx",
    "status": 1,
    "created_at": "2026-01-01T00:00:00Z"
  }
}
POST/open/v1/cloud-configs/pools/:pid/configs创建私人配置（写操作，需鉴权）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（与 user_id 二选一）
user_idheaderstring否用户ID
pidpathuuid是池 ID
titlebodystring是配置标题
contentbodystring否配置内容（任意文本，建议 JSON 字符串）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "cfg_xxxx",
    "title": "我的配置",
    "content": "{}",
    "status": 1
  }
}
PUT/open/v1/cloud-configs/configs/:cid更新私人配置

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（与 user_id 二选一）
user_idheaderstring否用户ID
cidpathuuid是配置 ID
titlebodystring否新标题
contentbodystring否新内容

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "cfg_xxxx",
    "title": "新标题",
    "content": "{...}"
  }
}
DELETE/open/v1/cloud-configs/configs/:cid删除私人配置

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（与 user_id 二选一）
user_idheaderstring否用户ID
cidpathuuid是配置 ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "ok": true
  }
}
POST/open/v1/cloud-configs/configs/:cid/share生成分享码（可设密码与领取次数上限）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（与 user_id 二选一）
user_idheaderstring否用户ID
cidpathuuid是配置 ID
passwordbodystring否可选分享密码（受池 allow_share_password 限制）
limitbodyint否可领取次数上限（受池 allow_share_limit 限制）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "share_code": "abcd1234",
    "share_password": "",
    "share_limit": 10,
    "share_used": 0
  }
}
POST/open/v1/cloud-configs/import用分享码导入配置（自动归属当前用户）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
card_noheaderstring否卡密号（与 user_id 二选一）
user_idheaderstring否用户ID
share_codebodystring是分享码
passwordbodystring否分享密码（若设置了）

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "cfg_xxxx",
    "title": "已导入配置",
    "content": "{...}"
  }
}

注入加固内部协议

1 个接口
POST/open/v1/app/register_dek注册 DEK 服务端分片（内部）

仅由平台的 ELF/APK 注入加固服务调用，不属于通用 OpenAPI，也不封装进常规 SDK。请求体使用软件专属注入密钥做 ChaCha20-Poly1305 加密，签名针对密文计算；普通客户端不要调用。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
X-Timestampheaderstring是Unix 时间戳
X-Nonceheaderstring是一次性随机数
X-Signatureheaderstring是注入签名密钥计算的 HMAC-SHA256 十六进制签名
encrypted_payloadrawstring是原始请求体：hex(nonce || ciphertext || tag)，解密后的 JSON 包含 32 字节 dek_server

响应示例

{
  "code": 0,
  "msg": "ok"
}