Inicio rápido

1. Crear una clave API

Acceda al portal de clientes, sección "KernelHost API" y cree una clave. Elija únicamente los permisos que realmente necesite (por defecto: solo lectura). El secreto se muestra una sola vez; guárdelo de forma segura en su gestor de secretos.

2. Almacenar las credenciales

Guarde la clave y el secreto como variables de entorno. Nunca en el código, nunca en un repositorio.

# .env o perfil de shell
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Enviar su primera petición

Liste los productos disponibles. La firma se construye sobre método, ruta, marca de tiempo, nonce y hash del cuerpo.

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. Realizar un pedido

Importante: POST /v1/orders requiere un Idempotency-Key y un nombre de host. Si tras un error de red repite la petición con el mismo Idempotency-Key, recibirá de nuevo la misma respuesta y no se creará un segundo pedido. Las opciones configurables que omita (por ejemplo, la ubicación o el sistema operativo) reciben el primer valor que se ofrece en la tienda.

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. Comprobar el estado y leer las credenciales

La respuesta del pedido contiene los service_ids. Consulte GET /v1/services/{id} hasta que status sea active y se haya asignado una dirección IP; el aprovisionamiento suele tardar entre unos segundos y unos pocos minutos. Después, GET /v1/services/{id}/credentials (permiso read:credentials) devuelve el nombre de host, las direcciones IP, el nombre de usuario y la contraseña, por ejemplo, para su inventario de 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. Registrar una URL de webhook (opcional)

Ya puede registrar una URL HTTPS por clave. El envío de eventos está en preparación; mientras tanto, utilice las consultas de estado del paso 5.