KernelHost Reseller API

What the Reseller API does

The KernelHost Reseller API exposes exactly the order and management actions you would otherwise click through in the customer portal. It lets you automate your reselling business, integrate KernelHost products into your own frontend or billing, and keep full control over per-key scopes, rate-limits and IP whitelists.

Every call is HMAC-SHA256 signed, replay-protected, processed idempotently (mandatory for orders), recorded in a tamper-evident audit log and optionally confirmed via webhook. Payments are debited from your credit balance first, then from your stored card. New cards can only be added in the customer portal (3-D Secure 2 enforced).

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

Table of contents

• 5-minute quickstart
• Authentication (HMAC-SHA256)
• Endpoint reference
• Error codes (RFC 7807)
• SDKs: PHP, Node.js, Python, Go
• Security and best practices
• Changelog

What you can do

• Browse products and prices (KVM rootservers, dedicated, webspace, Minecraft, VPN, unlimited traffic).
• Place orders (Idempotency-Key protects against double-charges on network retries).
• List your own services, check status, run actions (start, stop, reboot, reinstall, suspend, terminate).
• Read credentials of your own services only (separate scope, audited, optional confirmation email per access).
• Fetch invoices, check credit balance, download invoice PDFs.
• Register a per-key webhook for order, service and invoice events (Stripe-compatible signature scheme).

Maximum-security design

The API is designed assuming every call has direct financial impact and may expose sensitive server credentials. Security baseline is therefore well above usual REST defaults.

• HMAC-SHA256 request signature over method, path, timestamp, nonce and body hash. Constant-time comparison.
• Replay protection: timestamp window +-300s, single-use nonce cache for 600s.
• Secrets are persisted as AES-256-GCM ciphertexts only. Plaintext exists transiently in memory for signature verification. Master key lives outside the database.
• Granular per-key scopes. Dangerous scopes (read:credentials, write:orders) must be explicitly enabled. Default is read-only.
• Database-level data isolation: every query hard-filters on your account id. Cross-tenant access is impossible by design.

Example: query your own account

The request is signed in full with your secret. The secret never leaves the client memory; only the signature is transmitted.

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"

Frequently asked questions

Who can use the Reseller API?

Every existing KernelHost customer can create a key under "My Account → Reseller API" with their own label, scopes and IP whitelist. No separate reseller agreement is required: every publicly listed product is available via the API.

How are orders paid?

Order: credit balance first, then your stored payment method (credit card with 3-D Secure 2). If the payment is declined or no card is on file, the API returns HTTP 402 "Payment Required" with a specific reason (insufficient_credit_and_no_card, card_declined, card_expired). The order stays in "pending payment" for 24h and is then auto-cancelled.

Can I read service passwords via the API?

Yes, but only for your own services and only with the explicit read:credentials scope, which has to be enabled when the key is created. Every access produces an audit-log entry credentials.read; on request you can additionally receive a confirmation email to your account address so silent abuse is impossible.

What happens if my secret is compromised?

You rotate the secret with a single click in the customer portal. The old secret is invalidated immediately, all running sessions revoked. On suspicious auth failures (5 in 10 minutes) the system auto-locks the key for 15 minutes and emails you.