KernelHost API

O que a KernelHost API (API de Revenda) faz

A API de Revenda da KernelHost expõe exatamente as ações de pedido e gestão que você executaria clicando no portal do cliente. Permite automatizar o seu negócio de revenda, integrar produtos KernelHost no seu próprio frontend ou sistema de faturamento, e manter controle total sobre escopos, limites de taxa e lista de IPs permitidos por chave API.

Cada chamada é assinada com HMAC-SHA256, protegida contra replay, processada de forma idempotente (obrigatório para encomendas) e registada num log de auditoria à prova de adulteração. Os pagamentos são debitados primeiro do seu saldo de crédito e depois do cartão guardado. Por motivos de segurança, só é possível adicionar novos cartões no portal do cliente (3-D Secure 2).

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

Sumário

• Início rápido em 5 minutos
• Autenticação (HMAC-SHA256)
• Referência de endpoints
• Códigos de erro (RFC 7807)
• SDKs e exemplos de código
• Segurança e boas práticas
• Changelog

O que você pode fazer

• Consultar produtos e preços (rootservers KVM, dedicados, webspace, Minecraft, VPN, tráfego ilimitado).
• Realizar pedidos (Idempotency-Key protege contra cobranças duplicadas em retentativas de rede).
• Listar os seus próprios serviços, verificar o respetivo estado e executar ações: start, stop, reboot, cancelamento no fim do período de faturação e revogação desse cancelamento.
• Ler credenciais apenas dos seus próprios serviços (escopo separado, auditado, e-mail de confirmação opcional por acesso).
• Obter faturas, consultar saldo de crédito, baixar PDFs de faturas.
• Guardar um URL de webhook por chave. O envio de eventos (encomendas, serviços e faturas) está em preparação; até lá, consulte o estado através de GET /v1/orders/{id} e GET /v1/services/{id}.

Design de segurança máxima

A API foi projetada partindo do pressuposto de que cada chamada tem impacto financeiro direto e pode expor credenciais sensíveis de servidor. A linha de base de segurança está, portanto, bem acima dos padrões REST habituais.

• Assinatura HMAC-SHA256 da requisição sobre método, caminho, timestamp, nonce e hash do corpo. Comparação em tempo constante.
• Proteção contra replay: janela de timestamp +-300s, cache de nonce de uso único por 600s.
• Segredos são persistidos exclusivamente como texto cifrado AES-256-GCM. O texto claro existe transitoriamente em memória apenas para verificação da assinatura. A chave mestra fica fora do banco de dados.
• Escopos granulares por chave API. Escopos perigosos (read:credentials, write:orders) precisam ser ativados explicitamente. O padrão é somente leitura.
• Isolamento de dados no nível do banco: cada consulta filtra rigidamente pelo id da sua conta. Acesso entre tenants é impossível por design.

Exemplo: consultar sua própria conta

A requisição é assinada por completo com o seu segredo. O segredo nunca sai da memória do cliente; apenas a assinatura é transmitida.

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"

Perguntas frequentes

Quem pode usar a API de Revenda?

Qualquer cliente existente da KernelHost pode criar chaves no portal do cliente, através da opção de menu "KernelHost API", cada uma com o seu próprio rótulo, escopos e lista de IPs permitidos. Apenas o titular da conta pode criar, rodar ou revogar chaves. Não é necessário nenhum contrato de revenda à parte: todos os produtos listados publicamente podem ser encomendados através da API.

Como os pedidos são pagos?

O pagamento segue esta ordem: primeiro o seu saldo de crédito, depois o seu método de pagamento guardado. Se o pagamento falhar ou não houver nenhum cartão registado, a API devolve HTTP 402 "Payment Required" com o motivo exato (insufficient_credit_and_no_card, card_declined, credit_apply_failed) e cancela a encomenda de imediato, pelo que não fica nenhuma encomenda por pagar.

Posso ler senhas de serviços pela API?

Sim, apenas para os seus próprios serviços e apenas com o escopo explícito read:credentials, que tem de ser ativado à parte ao criar a chave. A resposta contém o hostname, os endereços IP, o nome de utilizador e a palavra-passe. Cada acesso gera uma entrada credentials.read no log de auditoria e um e-mail de confirmação para o endereço da conta, pelo que um abuso silencioso não passa despercebido.

O que acontece se meu segredo for comprometido?

Pode rodar o secret com um único clique na área de cliente e o secret anterior deixa de ser válido de imediato. As tentativas de autenticação falhadas são registadas e limitadas por IP de origem, mas nunca bloqueiam a sua chave, pelo que ninguém consegue bloquear a sua integração apenas por conhecer o ID público da chave.