验证卡密

verify

验证卡密并绑定设备，返回运行时会话。

卡密公开接口

验证卡密

verify

验证卡密并绑定设备，返回运行时会话。

语法

POST /api/v1/card-keys/verify
Content-Type: application/json

参数

请求体为公共 JSON（见卡密验证 · 公共请求体）。

参数	类型	说明
`app_id`	`string`	应用 UUID 或短码 `app_code`
`code`	`string`	卡密明文
`device_fingerprint`	`string`	稳定设备指纹
`device_name`	`string?`	可选，绑定展示名
`client_meta`	`object?`	可选，客户端元数据
`package_name`	`string?`	APK 绑定策略启用时必填
`signing_cert_sha256`	`string?`	证书白名单启用时必填

返回值

成功时 ApiResponse.data 为运行时响应：

字段	类型	说明
`payload`	`object`	明文会话字段，或加密后的 `{ ciphertext }`
`signature`	`string \| null`	策略启签名时的服务端签名
`encrypted`	`boolean`	是否已加密 `payload`
`encrypt_algorithm`	`string \| null`	加密算法名
`sign_algorithm`	`string \| null`	签名算法名

运行时载荷

当 encrypted = false 时，payload 字段如下：

字段	类型	说明
`app_id`	`string`	应用 UUID
`card_key_id`	`string`	卡密 ID
`binding_id`	`string`	当前设备绑定 ID
`status`	`string`	卡密状态（如 `active`）
`expire_at`	`number \| null`	过期 Unix 秒；无过期为 `null`
`heartbeat_interval_secs`	`number`	建议心跳间隔（秒）
`offline_grace_secs`	`number`	离线宽限（秒）
`server_time`	`number`	服务端 Unix 秒
`session_token`	`string`	会话令牌（非 JWT）

说明

本接口仅适用于 Volt 卡密云服务。自行搭建服务端不适用（服务端 SDK 尚未开放）。

verify 用于在终端首次或再次激活卡密：校验应用与卡密状态 → 按策略绑定设备（未超过 max_devices）→ 返回运行时会话。

同一指纹已绑定且卡密仍有效时，通常可再次调用以复用绑定（不额外占槽）。策略启用加密或签名时，客户端须先解密 / 验签后再使用载荷。

应用须 active 且未封禁；卡密须未禁用、未过期、未吊销。

示例

curl -X POST https://api.example.com/api/v1/card-keys/verify \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "ck_a1b2c3d4",
    "code": "GAME-XXXX-XXXX",
    "device_fingerprint": "stable-device-id-001",
    "device_name": "Pixel 8"
  }'

成功响应示例（明文、未签名）：

{
  "code": 0,
  "message": "success",
  "data": {
    "payload": {
      "app_id": "019abc...",
      "card_key_id": "019def...",
      "binding_id": "019ghi...",
      "status": "active",
      "expire_at": null,
      "heartbeat_interval_secs": 60,
      "offline_grace_secs": 300,
      "server_time": 1720857600,
      "session_token": "<session-token>"
    },
    "signature": null,
    "encrypted": false,
    "encrypt_algorithm": null,
    "sign_algorithm": null
  },
  "timestamp": 1720857600
}

常见错误

错误码	HTTP	场景
`40014`	404	卡密不存在或不属于该应用
`40015`	403	卡密已禁用
`40016`	403	卡密已过期
`40017`	403	卡密已吊销
`40018`	409	设备绑定数已达策略上限
`40021`	400	签名策略已启用但服务端签名未配置 / 失败
`40022`	403	发卡应用已关闭
`40023`	403	发卡应用已被封禁
`40024`	403	包名或签名证书与策略白名单不匹配

加密响应

策略开启加密或签名时，算法、线格式与验签顺序见 加密与签名。

摘要：

加密：payload = { ciphertext }，算法见响应 encrypt_algorithm
签名：sign_algorithm = RSA-SHA256，原文为密文字符串或明文 JSON

语法

POST /api/v1/card-keys/verify
Content-Type: application/json

参数