KernelHost API

What the KernelHost API (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 signed with HMAC-SHA256, protected against replay, processed idempotently (mandatory for orders) and recorded in a tamper-evident audit log. Payments are charged to your credit balance first, then to your stored card. For security reasons, new cards can only be added in the customer portal (3-D Secure 2).

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

Table of contents

• 5-minute quickstart
• Authentication (HMAC-SHA256)
• Endpoint reference
• Error codes (RFC 7807)
• SDKs and code examples
• 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 their status and run actions: start, stop, reboot, cancellation at the end of the billing period and withdrawing that cancellation.
• Read credentials of your own services only (separate scope, audited, optional confirmation email per access).
• Fetch invoices, check credit balance, download invoice PDFs.
• Store a webhook URL per key. Event delivery (order, service and invoice events) is in preparation; until then, query the status via GET /v1/orders/{id} and GET /v1/services/{id}.

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/kernelhost_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?

Any existing KernelHost customer can create keys in the customer portal via the "KernelHost API" menu item, each with its own label, scopes and IP whitelist. Only the account owner can create, rotate or revoke keys. No separate reseller agreement is needed: all publicly listed products can be ordered via the API.

How are orders paid?

Order of payment: your credit balance first, then your stored payment method. If the payment fails or no card is on file, the API returns HTTP 402 "Payment Required" with a precise reason (insufficient_credit_and_no_card, card_declined, credit_apply_failed) and cancels the order right away, so no unpaid order is left behind.

Can I read service passwords via the API?

Yes, only for your own services and only with the explicit scope read:credentials, which has to be enabled separately when creating a key. The response contains hostname, IP addresses, username and password. Every access creates an audit log entry credentials.read and a confirmation email to the account address, so covert misuse does not go unnoticed.

What happens if my secret is compromised?

You rotate the secret with a single click in the customer portal and the old secret is invalid immediately. Failed authentication attempts are logged and throttled per source IP but never lock your key, so nobody can block your integration just by knowing your public key ID.