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

Open API 调用文档

所有接口供客户端程序直接调用，使用 app_id 进行鉴权，无需用户登录 Token。

Base URL

https://api.xxauth.com

认证方式

所有 Open API 接口均通过请求头 app_id 进行鉴权。

在「软件管理」中创建应用后，可获取对应的 app_id。将其添加到 HTTP 请求头即可。

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

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

默认响应统一为 { "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_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
categoryquerystring是配置分类（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

6 个接口
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"
  }
}
POST/open/v1/card/heartbeat单码卡密心跳验证

请求参数

参数名位置类型必填说明
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是卡密号

响应示例

{
  "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

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

当软件「安全配置」开启『注册邮箱验证』或『登录邮箱验证』时，调用注册/登录前先用本接口获取验证码。 register 场景：传 email，验证码发送到该邮箱； login 场景：传 username，后端据此查出账号绑定的邮箱再发送。 是否需要验证码由对应软件的安全配置开关决定，与平台全局邮箱验证开关无关。

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
scenebodystring是场景：register（注册）或 login（登录）
emailbodystring否register 场景必填，接收验证码的邮箱
usernamebodystring否login 场景必填，后端据此查出账号绑定邮箱

响应示例

{
  "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 控制上限，同一用户可在 N 台设备登录，超限时返回错误提示
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
  }
}
POST/open/v1/user/recharge用户充值（卡密充值）

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
user_idbodystring是用户ID
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用户心跳验证

请求参数

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

响应示例

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

请求参数

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

响应示例

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

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

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
user_idbodystring是用户ID
passwordbodystring是账户密码（必须）

响应示例

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

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
user_idbodystring是用户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用户修改密码

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
user_idbodystring是用户ID
old_passwordbodystring是旧密码
new_passwordbodystring是新密码

响应示例

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

软件信息 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
card_noheaderstring否卡密号（variables_auth_required 开启时必填）
user_idheaderstring否用户ID（variables_auth_required 开启时必填）

响应示例

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

应用验证 API

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

请求参数

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

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": true
  }
}

在线统计 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按函数名执行云逻辑脚本

请求参数

参数名位置类型必填说明
app_idheaderstring是应用ID
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
pidqueryuuid是池 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 二选一）
cidqueryuuid是配置 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
pidqueryuuid是池 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
cidqueryuuid是配置 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
cidqueryuuid是配置 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
cidqueryuuid是配置 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": "{...}"
  }
}