Cómo crear una clave de API y administrar tu servidor con la API del panel

Todo lo que haces con clics en el panel (encender el servidor, enviar un comando a la consola, editar un archivo) también se puede hacer con una solicitud HTTP. Es lo que permite que un bot de Discord reinicie el servidor de Minecraft con un comando, que un script vuelva a encender el servidor si se cae o que una rutina guarde un archivo de configuración cada día.

Esta guía muestra cómo crear la clave que da ese acceso y cómo usarla en las operaciones más comunes.

1. Qué puede hacer la clave de API

La clave actúa en nombre de tu cuenta. No tiene permisos separados: lo que tú puedes hacer en el panel, ella también puede, en todos los servidores de la cuenta. Las operaciones más usadas son:

• Energía: encender, apagar, reiniciar y forzar el apagado.
• Consola: enviar comandos como say, whitelist add o save-all.
• Consumo: leer el estado del servidor y el uso de CPU, memoria y disco.
• Archivos: listar carpetas, leer y escribir archivos.
• Copias de seguridad y tareas programadas: las mismas que aparecen en las pestañas del servidor.

2. Crear la clave

El panel puede mostrar las etiquetas en portugués; el nombre original va entre paréntesis.

1. Entra al panel en app.redhosting.com.br.
2. En el menú lateral, haz clic en Cuenta (Conta), o abre directamente app.redhosting.com.br/account.
3. Baja hasta el recuadro de claves, al final de la página, y haz clic en la pestaña Clave API (Chave API); la pestaña de al lado es la de clave SSH.
4. En Descripción (Descrição), escribe para qué sirve la clave, por ejemplo bot de discord. Son al menos 4 caracteres, y es ese nombre el que te dirá, meses después, qué clave borrar.
5. En IP permitidas (IPs Permitidos), pon la IP de la máquina que usará la clave, una por línea. Dejarlo en blanco permite usarla desde cualquier lugar de internet.
6. Haz clic en Crear (Criar).

La ventana Tu clave API (Sua Chave API) muestra la clave completa, que empieza con ptlc_. Cópiala y guárdala en un lugar seguro: no se vuelve a mostrar. Si la pierdes, borra la clave y crea otra.

3. Encontrar el identificador del servidor

Cada llamada tiene que indicar en qué servidor actuar. El identificador aparece en la barra de direcciones cuando abres el servidor en el panel:

https://app.redhosting.com.br/server/1a2b3c4d

El identificador es la parte después de /server/; en el ejemplo, 1a2b3c4d. Los ejemplos de abajo usan TU_SERVIDOR en su lugar y TU_CLAVE en lugar de la clave.

4. Primera prueba

Cada solicitud lleva la clave y la indicación de que la conversación es en JSON. Este comando lista los servidores de la cuenta y confirma que la clave funciona:

curl https://app.redhosting.com.br/api/client \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Accept: application/json"

La respuesta trae un elemento por servidor. El campo identifier de cada uno es el mismo identificador del paso anterior.

5. Administrar el servidor

Ver si está encendido y cuánto consume

curl https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR/resources \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Accept: application/json"

El campo current_state indica el estado: running, starting, stopping u offline. En resources vienen la memoria y el disco en bytes y la CPU en porcentaje.

Encender, apagar y reiniciar

curl -X POST https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR/power \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"signal": "restart"}'

El signal acepta start, stop, restart y kill. Prefiere stop: apaga con calma y deja que el servidor guarde lo que está en memoria. kill corta en el acto, como desenchufar, y puede corromper el mundo o archivos abiertos.

Enviar un comando a la consola

curl -X POST https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR/command \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Reinicio en 5 minutos"}'

El comando llega a la consola exactamente como si lo hubieras escrito ahí. El servidor tiene que estar encendido; apagado, la respuesta es un error 502.

Leer y escribir archivos

Para listar una carpeta:

curl "https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR/files/list?directory=/" \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Accept: application/json"

Para leer un archivo (la respuesta es el contenido puro, no JSON):

curl "https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR/files/contents?file=/server.properties" \
  -H "Authorization: Bearer TU_CLAVE"

Para escribir, el cuerpo de la solicitud es todo el contenido nuevo del archivo, que se reemplaza:

curl -X POST "https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR/files/write?file=/motd.txt" \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Accept: application/json" \
  --data-binary @motd.txt

Resumen de las direcciones. Todas empiezan con https://app.redhosting.com.br/api/client/servers/TU_SERVIDOR:

6. Ejemplo: volver a encender el servidor si se cae

Un script en Node.js (versión 18 o más reciente) que comprueba el estado y enciende el servidor cuando lo encuentra apagado. La clave viene de una variable de entorno, no escrita en el código: así no termina en GitHub junto con el resto.

const PANEL = 'https://app.redhosting.com.br/api/client';
const SERVER = 'TU_SERVIDOR';
const headers = {
  Authorization: `Bearer ${process.env.PANEL_API_KEY}`,
  Accept: 'application/json',
  'Content-Type': 'application/json',
};

async function check() {
  const response = await fetch(`${PANEL}/servers/${SERVER}/resources`, { headers });
  if (!response.ok) throw new Error(`La API respondió ${response.status}`);

  const { attributes } = await response.json();
  if (attributes.current_state === 'offline') {
    await fetch(`${PANEL}/servers/${SERVER}/power`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ signal: 'start' }),
    });
    console.log('El servidor estaba apagado: encendiéndolo.');
  }
}

check().catch((error) => console.error(error.message));

Ejecutado cada pocos minutos con una tarea programada del sistema, vuelve a encender el servidor tras una caída. No lo ejecutes con un intervalo demasiado corto: mira el límite de solicitudes en la siguiente sección.

7. Errores comunes

8. Seguridad

• Una clave por uso. Una para el bot, otra para el script de copias. Si una se filtra, borras solo esa y el resto sigue funcionando.
• Rellena IP permitidas siempre que sepas desde dónde se usará la clave.
• Guarda la clave en una variable de entorno o en un archivo .env que esté en el .gitignore, nunca dentro del código.
• Revisa el "Último uso" de cada clave en la pestaña Clave API. Una clave que ya no usas pero que sigue usándose es una clave filtrada.
• Para revocar, haz clic en la papelera junto a la clave. El borrado vale al instante para todas las solicitudes.