KernelHost API

Qué ofrece la KernelHost API (API de Revendedores)

La API de Revendedores de KernelHost expone exactamente las mismas acciones de pedido y gestión que usted realizaría manualmente en el portal de clientes. Le permite automatizar su negocio de reventa, integrar los productos de KernelHost en su propio frontend o sistema de facturación, y mantener el control total sobre permisos, límites de tasa y lista blanca de IP por cada clave API.

Cada llamada se firma con HMAC-SHA256, queda protegida contra ataques de repetición, se procesa de forma idempotente (obligatorio en los pedidos) y se documenta en un registro de auditoría a prueba de manipulación. Los pagos se descuentan primero de su saldo y, después, se cargan en su tarjeta registrada. Por motivos de seguridad, las tarjetas nuevas solo pueden añadirse en el portal de clientes (3-D Secure 2).

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

Índice

• Inicio rápido en 5 minutos
• Autenticación (HMAC-SHA256)
• Referencia de endpoints
• Códigos de error (RFC 7807)
• SDKs y ejemplos de código
• Seguridad y buenas prácticas
• Historial de cambios

Qué puede hacer con la API

• Consultar productos y precios (servidores raíz KVM, dedicados, webspace, Minecraft, VPN, tráfico ilimitado).
• Realizar pedidos (Idempotency-Key protege frente a cargos duplicados ante reintentos de red).
• Listar sus propios servicios, comprobar su estado y ejecutar acciones: arranque (start), parada (stop), reinicio (reboot), cancelación al final del periodo de facturación y revocación de dicha cancelación.
• Leer las credenciales únicamente de sus propios servicios (permiso separado, auditado, con correo de confirmación opcional en cada acceso).
• Obtener facturas, comprobar el saldo y descargar PDFs de facturas.
• Registrar una URL de webhook por clave. El envío de eventos (pedidos, servicios y facturas) está en preparación; mientras tanto, consulte el estado mediante GET /v1/orders/{id} y GET /v1/services/{id}.

Diseño de máxima seguridad

La API está diseñada partiendo de la base de que cada llamada tiene impacto financiero directo y puede exponer credenciales sensibles del servidor. Por ello, las exigencias de seguridad están claramente por encima del estándar habitual en REST.

• Firma de petición HMAC-SHA256 sobre método, ruta, marca de tiempo, nonce y hash del cuerpo. Comparación en tiempo constante.
• Protección contra repetición: ventana de marca de tiempo +-300s, caché de nonce de un solo uso durante 600s.
• Los secretos se almacenan persistentemente solo como cifrado AES-256-GCM. El texto en claro existe únicamente de forma transitoria en memoria para la verificación de firma. La clave maestra reside fuera de la base de datos.
• Permisos granulares por clave. Los permisos peligrosos (read:credentials, write:orders) deben activarse de forma explícita. El valor por defecto es solo lectura.
• Aislamiento de datos a nivel de base de datos: cada consulta filtra estrictamente por el identificador de su cuenta. El acceso entre clientes es imposible por diseño.

Ejemplo: consultar la información de su propia cuenta

La petición se firma íntegramente con su secreto. El secreto nunca abandona la memoria del cliente; solo se transmite la firma.

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"

Preguntas frecuentes

¿Quién puede utilizar la API de Revendedores?

Cualquier cliente actual de KernelHost puede crear claves en el portal de clientes desde la opción de menú "KernelHost API", cada una con su propia etiqueta, sus propios permisos y su propia lista blanca de IP. Solo el titular de la cuenta puede crear, rotar o revocar claves. No se necesita ningún acuerdo de reventa aparte: todos los productos que se ofrecen públicamente pueden pedirse a través de la API.

¿Cómo se pagan los pedidos?

Primero se utiliza su saldo y, después, su método de pago registrado. Si el pago falla o no hay ninguna tarjeta registrada, la API devuelve HTTP 402 "Payment Required" con un motivo concreto (insufficient_credit_and_no_card, card_declined, credit_apply_failed) y cancela el pedido de inmediato, de modo que no queda ningún pedido sin pagar.

¿Puedo leer las contraseñas de los servicios mediante la API?

Sí, pero solo de sus propios servicios y únicamente con el permiso explícito read:credentials, que debe activarse por separado al crear una clave. La respuesta contiene el nombre de host, las direcciones IP, el nombre de usuario y la contraseña. Cada acceso genera una entrada credentials.read en el registro de auditoría y envía un correo de confirmación a la dirección de la cuenta, de modo que un uso indebido encubierto no pasa desapercibido.

¿Qué ocurre si mi secreto resulta comprometido?

Puede rotar el secreto con un solo clic en el área de cliente y el secreto anterior deja de ser válido de inmediato. Los intentos de autenticación fallidos se registran y se limitan por IP de origen, pero nunca bloquean su clave, de modo que nadie puede bloquear su integración solo por conocer el ID público de su clave.