Início rápido

1. Crie uma chave API

Inicie sessão no portal do cliente, em "KernelHost API", e crie uma chave. Escolha apenas os escopos de que realmente precisa (predefinição: só de leitura). O segredo só é mostrado uma vez; guarde-o em segurança no seu gestor de segredos.

2. Armazene as credenciais

Salve a chave API e o segredo como variáveis de ambiente. Nunca no código, nunca em um repositório.

# .env ou perfil do shell
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Envie sua primeira requisição

Liste os produtos disponíveis. A assinatura é construída sobre método, caminho, timestamp, nonce e hash do corpo.

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

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

4. Faça um pedido

Importante: POST /v1/orders exige um Idempotency-Key e um hostname. Se repetir o pedido com o mesmo Idempotency-Key após um erro de rede, recebe a mesma resposta em vez de uma segunda encomenda. As opções configuráveis que omitir (por exemplo, a localização ou o sistema operativo) recebem o primeiro valor oferecido na loja.

BODY='{"product_id":42,"billing_cycle":"monthly","hostname":"web01.example.com"}'
IDEM="order-web01-$(date +%Y%m%d)"
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG_INPUT=$(printf 'POST\n/v1/orders\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')

curl -X POST https://www.kernelhost.com/cp/kernelhost_api/v1/orders \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  --data "$BODY"

5. Verifique o estado e obtenha as credenciais

A resposta ao pedido de encomenda indica os service_ids. Consulte GET /v1/services/{id} até que o campo status tenha o valor active e esteja atribuído um endereço IP; a configuração costuma demorar entre alguns segundos e alguns minutos. Em seguida, GET /v1/services/{id}/credentials (escopo read:credentials) devolve o hostname, os endereços IP, o nome de utilizador e a palavra-passe, por exemplo para o seu inventário Ansible.

kh_get() {
  TS=$(date +%s)
  NONCE=$(openssl rand -hex 16)
  BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
  SIG_INPUT=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$TS" "$NONCE" "$BODY_SHA256")
  SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')
  curl -s "https://www.kernelhost.com/cp/kernelhost_api$1" \
    -H "KH-Key: $KH_KEY" \
    -H "KH-Timestamp: $TS" \
    -H "KH-Nonce: $NONCE" \
    -H "KH-Signature: $SIG"
}

kh_get /v1/services/1234
kh_get /v1/services/1234/credentials

6. Guarde um URL de webhook (opcional)

Já pode guardar um URL HTTPS por chave. O envio de eventos está em preparação; até lá, utilize as consultas de estado do passo 5.