欢の授权站授权接口文档

curl --request GET "$BASE_URL/health" \
  --header 'Accept: application/json'

{
  "status": "ok",
  "service": "huanware-license-server",
  "version": "1.0.3",
  "database": "ok",
  "time": "2026-09-14T12:00:00+08:00",
  "domestic_status": "online",
  "overseas_status": "online",
  "domestic_http_status": 200,
  "overseas_http_status": 200,
  "failover_endpoint": "https://license-cf.xkshop.top",
  "failover_status": "standby_not_probed"
}

curl --request GET "$BASE_URL/api/v1/products" \
  --header 'Accept: application/json'

{
  "data": [
    {
      "code": "PLUGIN_PRO",
      "slug": "plugin-pro",
      "name": "专业插件",
      "version_label": "1.0",
      "description": "示例产品",
      "client_type": "module",
      "verification_policy": "client_managed",
      "default_binding_mode": "wildcard_domain"
    }
  ]
}

curl --request GET "$BASE_URL/api/v1/public-key" \
  --header 'Accept: application/json'

{
  "data": {
    "algorithm": "ed25519",
    "public_key": "<32 字节公钥的标准 Base64>",
    "encoding": "base64",
    "signed_payload_encoding": "base64url-no-padding"
  }
}

curl --request POST "$BASE_URL/api/v1/licenses/public-lookup" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "domain": "shop.example.com",
  "client_nonce": "demo-client-nonce-0001"
}'

{
  "purpose": "license_status_lookup_v1",
  "license_active": true,
  "query_match": true,
  "code": "LOOKUP_ACTIVE_MATCH",
  "matches": [
    {
      "product_code": "PLUGIN_PRO",
      "product_name": "专业插件",
      "license_active": true,
      "query_match": true,
      "binding_mode": "wildcard_domain",
      "matched_by": [
        "domain"
      ],
      "license_id": null,
      "licensee": null,
      "custom_info": {}
    }
  ],
  "client_nonce": "demo-client-nonce-0001",
  "runtime_verification_required": true
}

curl --request POST "$BASE_URL/api/v1/licenses/lookup" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "license_key": "HW-PLUG-ABCD-EFGH-JKLM-NPQR",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "client_nonce": "demo-client-nonce-0001"
}'

{
  "purpose": "license_status_lookup_v1",
  "license_active": true,
  "query_match": true,
  "code": "LOOKUP_ACTIVE_MATCH",
  "product_code": "PLUGIN_PRO",
  "binding_mode": "wildcard_domain",
  "binding_state": "matched",
  "active_bindings": 1,
  "bound_domain": "example.com",
  "queried_domain": "shop.example.com",
  "runtime_verification_required": true,
  "client_nonce": "demo-client-nonce-0001"
}

curl --request POST "$BASE_URL/api/v1/licenses/verify" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "license_key": "HW-PLUG-ABCD-EFGH-JKLM-NPQR",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "custom_info": {
    "client_version": "1.0.0"
  },
  "client_nonce": "demo-client-nonce-0001"
}'

{
  "valid": true,
  "code": "VALID",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "binding_mode": "wildcard_domain",
  "bound_domain": "example.com",
  "activation_required": true,
  "activation_id": "<activation_uuid>",
  "entitlements": [
    "updates"
  ],
  "checked_at": "2026-09-14T12:00:00+08:00",
  "next_check_at": null,
  "lease_token": "HWL-<secret>",
  "lease_expires_at": "2026-09-15T18:00:00+08:00",
  "verification_policy": "client_managed",
  "client_nonce": "demo-client-nonce-0001"
}

curl --request POST "$BASE_URL/api/v1/licenses/activate" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "license_key": "HW-PLUG-ABCD-EFGH-JKLM-NPQR",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "custom_info": {
    "client_version": "1.0.0"
  },
  "client_nonce": "demo-client-nonce-0001"
}'

{
  "activated": true,
  "already_active": false,
  "code": "ACTIVATED",
  "license_id": "<license_uuid>",
  "activation_id": "<activation_uuid>",
  "activation_token": "HWA-<secret>",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "installation_id": "",
  "binding_mode": "wildcard_domain",
  "client_nonce": "demo-client-nonce-0001",
  "activated_at": "2026-09-14T12:00:00+08:00",
  "next_check_at": "2026-09-14T12:05:00+08:00"
}

curl --request POST "$BASE_URL/api/v1/instances/report" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "installation_id": "site-01",
  "custom_info": {
    "client_version": "1.0.0",
    "runtime": "php-8.2"
  },
  "client_nonce": "demo-client-nonce-0001"
}'

{
  "reported": true,
  "code": "REPORTED",
  "message": "安装实例信息已记录。",
  "report_id": "<report_uuid>",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "installation_id": "site-01",
  "custom_info": {
    "client_version": "1.0.0",
    "runtime": "php-8.2"
  },
  "reported_ip": "203.0.113.10",
  "reported_at": "2026-09-14T12:00:00+08:00",
  "client_nonce": "demo-client-nonce-0001"
}

curl --request POST "$BASE_URL/api/v1/licenses/deactivate" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "license_key": "HW-PLUG-ABCD-EFGH-JKLM-NPQR",
  "product_code": "PLUGIN_PRO",
  "activation_token": "HWA-<replace-with-activation-token>",
  "domain": "shop.example.com"
}'

{
  "deactivated": true,
  "code": "DEACTIVATED",
  "message": "该实例已解绑，可按授权额度重新激活。",
  "product_code": "PLUGIN_PRO",
  "domain": "shop.example.com",
  "installation_id": "",
  "deactivated_at": "2026-09-14T12:00:00+08:00"
}

管理接口 · 仅可信服务端使用

curl --request POST "$BASE_URL/internal/v1/licenses" \
  --header 'Accept: application/json' \
  --header "X-Admin-Key: $ADMIN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "user_id": 2,
  "product_code": "PLUGIN_PRO",
  "plan": "professional",
  "activation_mode": "wildcard_domain",
  "max_activations": 1,
  "reset_limit_per_period": 3,
  "allowed_domains": [
    "example.com",
    "*.example.com"
  ],
  "entitlements": [
    "updates"
  ]
}'

{
  "data": {
    "license_id": "<license_uuid>",
    "license_key": "HW-PLUG-ABCD-EFGH-JKLM-NPQR",
    "product_code": "PLUGIN_PRO",
    "customer_name": "示例用户",
    "plan": "professional",
    "activation_mode": "wildcard_domain",
    "max_activations": 1,
    "reset_limit_per_period": 3,
    "starts_at": "2026-09-14T12:00:00+08:00",
    "expires_at": null,
    "allowed_domains": [
      "example.com",
      "*.example.com"
    ],
    "entitlements": [
      "updates"
    ]
  }
}

curl --request GET "$BASE_URL/internal/v1/failover-snapshot?nonce=demo-client-nonce-0001" \
  --header 'Accept: application/json' \
  --header "X-Failover-Key: $FAILOVER_SYNC_KEY"

{
  "purpose": "license_failover_snapshot_v1",
  "schema_version": 1,
  "snapshot_id": "<snapshot_uuid>",
  "client_nonce": "demo-client-nonce-0001",
  "generated_at": "2026-09-14T12:00:00+08:00",
  "valid_until": "2026-09-14T18:00:00+08:00",
  "products": "<当前启用产品数组>",
  "licenses": "<授权码哈希、状态范围、白名单、权益和有效绑定数组>"
}

绑定方式与泛域名规则

泛域名按内置 Public Suffix List（含私有后缀）确定可注册主域名：example.co.uk 不会被当成 co.uk，alice.github.io 与 bob.github.io 不会共享授权。IP、localhost、仅公共后缀和无法识别的后缀不能用于泛域名模式。域名白名单仍按实际请求域名检查；*.example.com 仅允许子域名，若也要允许主域名，请同时填写 example.com。修改产品默认绑定方式只影响以后签发的授权，不自动转换已有授权。

响应结构与安全验签

lookup、public-lookup、verify、activate、instances/report、deactivate 的成功 HTTP 响应使用下面的签名封装。签名保护的是 signed_payload 解码后的原始字节（即 data 的 JSON），不包括外层 request_id。

{
  "request_id": "<request_uuid>",
  "data": {
    "code": "VALID",
    "client_nonce": "demo-client-nonce-0001"
  },
  "signed_payload": "<data JSON 的 Base64URL，无填充>",
  "signature": "<Ed25519 签名的标准 Base64>",
  "signature_algorithm": "ed25519"
}

1. 先检查 HTTP 状态；业务错误可能位于 HTTP 200 的签名 data 中，例如 valid:false，必须继续检查。
2. 对 signed_payload 做 Base64URL 无填充解码；对 signature 和固定的公钥做标准 Base64 解码，分别应为 64 和 32 字节。
3. 使用 Ed25519 对解码后的原始载荷字节验签，不能把外层 data 重新 JSON 序列化后验签。
4. 验签成功后再解析载荷，核对产品、请求域名、支持随机数的接口的 client_nonce，以及 checked_at / lease_expires_at 等时间；以载荷为准，不单独信任外层 data。
5. 请求 nonce 每次重新生成并保留到响应校验完毕；deactivate 不接收 nonce，需核对目标字段和解绑时间。公钥应预先可信固定，不要在验签失败时无条件换成网络返回的新公钥。

时间字段以带 +08:00 的北京时间 RFC3339 输出。授权码、activation_token、lease_token 和 X-Admin-Key 都是秘密；上报 custom_info 不得包含这些值。

{
  "error": {
    "code": "ACTIVATION_LIMIT_REACHED",
    "message": "该授权的激活数量已达到上限。"
  }
}