密钥验证 API 对接指南

POST /api/validate
Content-Type: application/json
X-Access-Key: ak_xxxxxxxxxxxxxxxxx
X-Api-Signature: <hmac-sha256>

{
  "key": "LICENSE_KEY",
  "machine_id": "DEVICE-001",
  "device_limit": 5,
  "timestamp": 1779123456,
  "nonce": "b5f2b0b7b2564bb9a48b7f6a3d3d83a1"
}

import hashlib
import hmac
import json

def generate_signature(secret_key: str, body: dict) -> str:
    payload = json.dumps(body, sort_keys=True, separators=(",", ":"))
    return hmac.new(
        secret_key.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

import hashlib
import hmac
import json
import secrets
import time

import requests

ACCESS_KEY = "ak_xxxxxxxxxxxxxxxxx"
SECRET_KEY = "创建或轮换时展示的一次性secret_key"
API_ENDPOINT = "https://your-domain.com/api/validate"


def generate_signature(secret_key: str, body: dict) -> str:
    payload = json.dumps(body, sort_keys=True, separators=(",", ":"))
    return hmac.new(
        secret_key.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()


body = {
    "key": "LICENSE_KEY",
    "machine_id": "DEVICE-001",
    "device_limit": 5,
    "timestamp": int(time.time()),
    "nonce": secrets.token_hex(16),
}

response = requests.post(
    API_ENDPOINT,
    json=body,
    headers={
        "X-Access-Key": ACCESS_KEY,
        "X-Api-Signature": generate_signature(SECRET_KEY, body),
    },
    timeout=10,
)

print(response.status_code)
print(response.json())

const crypto = require('crypto');

const ACCESS_KEY = 'ak_xxxxxxxxxxxxxxxxx';
const SECRET_KEY = '创建或轮换时展示的一次性secret_key';
const API_ENDPOINT = 'https://your-domain.com/api/validate';

function stableStringify(value) {
  const keys = Object.keys(value).sort();
  const ordered = {};
  for (const key of keys) ordered[key] = value[key];
  return JSON.stringify(ordered);
}

function generateSignature(secretKey, body) {
  return crypto
    .createHmac('sha256', Buffer.from(secretKey, 'utf8'))
    .update(Buffer.from(stableStringify(body), 'utf8'))
    .digest('hex');
}

async function validateLicense() {
  const body = {
    key: 'LICENSE_KEY',
    machine_id: 'DEVICE-001',
    device_limit: 5,
    timestamp: Math.floor(Date.now() / 1000),
    nonce: crypto.randomBytes(16).toString('hex'),
  };

  const response = await fetch(API_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Access-Key': ACCESS_KEY,
      'X-Api-Signature': generateSignature(SECRET_KEY, body),
    },
    body: JSON.stringify(body),
  });

  console.log(response.status, await response.json());
}

validateLicense().catch(console.error);

{
  "valid": true,
  "status": "active",
  "duration_type": "1个月",
  "activated_at": "2026-05-20T18:30:00+08:00",
  "expire_at": "2026-06-19T18:30:00+08:00",
  "message": "许可证已成功激活",
  "device_binding": {
    "action": "bound_new",
    "message": "设备已完成绑定",
    "machine_id_hash": "b7d8f0f2a4c9e1d6...",
    "bound_device_count": 1,
    "device_limit": 3
  },
  "signed_license": {
    "alg": "Ed25519",
    "kid": "sm-license-ed25519-signing-key",
    "payload": "base64url-json-payload",
    "signature": "base64url-signature"
  }
}

{
  "valid": true,
  "status": "active",
  "duration_type": "1个月",
  "activated_at": "2026-05-20T18:30:00+08:00",
  "expire_at": "2026-06-19T18:30:00+08:00",
  "remaining_days": 29,
  "device_binding": {
    "action": "verified_existing",
    "message": "设备已绑定，本次为正常复核",
    "machine_id_hash": "b7d8f0f2a4c9e1d6...",
    "bound_device_count": 1,
    "device_limit": 3
  },
  "signed_license": {
    "alg": "Ed25519",
    "kid": "sm-license-ed25519-signing-key",
    "payload": "base64url-json-payload",
    "signature": "base64url-signature"
  }
}

// v1.4.0 起响应时间已携带 +08:00 时区偏移，可直接解析
function parseLicenseTime(value) {
  if (!value) return null;
  return new Date(value);
}

function formatShanghaiTime(value) {
  const date = parseLicenseTime(value);
  if (!date) return '永久有效';
  return new Intl.DateTimeFormat('zh-CN', {
    timeZone: 'Asia/Shanghai',
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    hour12: false,
  }).format(date);
}

// v1.4.0 起响应时间已携带 +08:00 时区偏移，可直接解析
DateTime? parseLicenseTime(String? value) {
  if (value == null || value.isEmpty) return null;
  return DateTime.parse(value);
}

{
  "detail": {
    "valid": false,
    "code": "DEVICE_LIMIT_EXCEEDED",
    "message": "设备绑定数量已达上限"
  }
}