KernelHost Reseller API

Reseller API 的功能

KernelHost Reseller API 完整还原了您在客户门户中点击操作的下单与管理动作。您可以借此自动化分销业务，将 KernelHost 产品集成到自己的前端或计费系统中，同时对每个 API 密钥的权限范围、速率限制和 IP 白名单保持完全控制。

每一次调用都使用 HMAC-SHA256 签名，受重放保护，按幂等方式处理（订单为强制要求），记录在防篡改的审计日志中，并可选通过 Webhook 进行确认。付款先从您的余额扣除，再从已绑定的信用卡扣除。出于安全考虑，新信用卡只能在客户门户中添加（强制 3-D Secure 2）。

https://www.kernelhost.com/cp/kh_reseller_api/v1

目录

• 5 分钟快速上手
• 身份验证（HMAC-SHA256）
• 端点参考
• 错误代码（RFC 7807）
• SDK：PHP、Node.js、Python、Go
• 安全与最佳实践
• 变更日志

您可以做什么

• 浏览产品与价格（KVM 根服务器、独立服务器、虚拟主机、Minecraft、VPN、无限流量）。
• 提交订单（Idempotency-Key 在网络重试时防止重复扣款）。
• 列出您自己的服务，查询状态，执行操作（启动、停止、重启、重装、暂停、终止）。
• 仅读取您自己服务的凭据（独立权限范围，全程审计，每次访问可选发送确认邮件）。
• 获取发票、查询余额、下载发票 PDF。
• 为每个 API 密钥注册 Webhook，接收订单、服务与发票事件（兼容 Stripe 的签名方案）。

极致安全设计

该 API 的设计前提是：每一次调用都可能产生直接的财务影响，并可能涉及敏感的服务器凭据。因此其安全基线明显高于一般 REST 默认水平。

• 对方法、路径、时间戳、随机数与请求体哈希执行 HMAC-SHA256 请求签名。比较过程采用恒定时间算法。
• 重放保护：时间戳容忍窗口 +-300 秒，一次性随机数缓存 600 秒。
• 密钥仅以 AES-256-GCM 密文形式持久化存储。明文仅在内存中短暂存在用于签名验证。主密钥保存在数据库之外。
• 每个密钥拥有细粒度的权限范围。危险权限范围（read:credentials、write:orders）必须显式启用，默认仅为只读。
• 数据库层面的数据隔离：每条查询都强制按您的账户 ID 过滤。跨租户访问在设计上完全不可能。

示例：查询自己的账户信息

请求使用您的密钥对整体内容进行签名。密钥永远不会离开客户端内存，仅传输签名值。

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIG_INPUT=$(printf 'GET\n/v1/me\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $2}')

curl https://www.kernelhost.com/cp/kh_reseller_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

常见问题

谁可以使用 Reseller API？

每一位现有的 KernelHost 客户都可以在「我的账户 → Reseller API」中创建密钥，自定义标签、权限范围与 IP 白名单。无需另行签订分销协议，所有公开销售的产品均可通过 API 订购。

订单如何付款？

扣款顺序为：先使用您的余额，再使用已绑定的支付方式（带 3-D Secure 2 的信用卡）。若付款被拒或未绑定信用卡，API 返回 HTTP 402「Payment Required」并附带明确原因（insufficient_credit_and_no_card、card_declined、card_expired）。订单将在「pending payment」状态保留 24 小时，随后自动取消。

我可以通过 API 读取服务密码吗？

可以，但仅限于您自己的服务，并且必须明确启用 read:credentials 权限范围（该权限范围需在创建密钥时单独开启）。每一次访问都会生成 credentials.read 审计日志条目；如有需要，您还可以另行收到发送至账户邮箱的确认邮件，从而杜绝任何隐蔽滥用。

如果我的密钥泄露了怎么办？

您可以随时在客户门户中一键轮换密钥。旧密钥立即失效，所有正在进行的会话被吊销。若出现可疑的身份验证失败（10 分钟内 5 次），系统会自动锁定该密钥 15 分钟，并通过邮件通知您。