Como criar uma chave de API e gerenciar seu servidor pela API do painel

Tudo o que você faz clicando no painel — ligar o servidor, mandar um comando no console, editar um arquivo — também pode ser feito por uma requisição HTTP. É o que permite um bot de Discord reiniciar o servidor de Minecraft com um comando, um script religar o servidor se ele cair ou uma rotina salvar um arquivo de configuração todo dia.

Este guia mostra como criar a chave que dá esse acesso e como usá-la nas operações mais comuns.

1. O que a chave de API pode fazer

A chave age em nome da sua conta. Ela não tem permissões separadas: o que você pode fazer no painel, ela também pode, em todos os servidores da conta. As operações mais usadas são:

• Energia — ligar, desligar, reiniciar e forçar o desligamento.
• Console — enviar comandos, como say, whitelist add ou save-all.
• Consumo — ler o estado do servidor e o uso de CPU, memória e disco.
• Arquivos — listar pastas, ler e gravar arquivos.
• Backups e agendamentos — os mesmos que aparecem nas abas do servidor.

2. Criando a chave

1. Entre no painel em app.redhosting.com.br.
2. No menu lateral, clique em Conta — ou abra direto app.redhosting.com.br/account.
3. Role até o quadro de chaves, no fim da página, e clique na aba Chave API (a aba ao lado é a de Chave SSH).
4. Em Descrição, escreva para que a chave serve — por exemplo, bot do discord. São pelo menos 4 caracteres, e é esse nome que vai te dizer, meses depois, qual chave apagar.
5. Em IPs Permitidos, coloque o IP da máquina que vai usar a chave, um por linha. Deixar em branco libera o uso de qualquer lugar da internet.
6. Clique em Criar.

A janela Sua Chave API mostra a chave completa, que começa com ptlc_. Copie e guarde num lugar seguro: ela não é mostrada de novo. Se perder, apague a chave e crie outra.

3. Descobrindo o identificador do servidor

Cada chamada precisa dizer em qual servidor agir. O identificador aparece na barra de endereço quando você abre o servidor no painel:

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

O identificador é a parte depois de /server/ — no exemplo, 1a2b3c4d. Os exemplos abaixo usam SEU_SERVIDOR no lugar dele e SUA_CHAVE no lugar da chave.

4. Primeiro teste

Toda requisição leva três cabeçalhos: a chave, e a indicação de que a conversa é em JSON. Este comando lista os servidores da conta e confirma que a chave funciona:

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

A resposta traz um item para cada servidor. O campo identifier de cada um é o mesmo identificador do passo anterior.

5. Gerenciando o servidor

Ver se está ligado e quanto consome

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

O campo current_state diz o estado: running, starting, stopping ou offline. Em resources vêm a memória e o disco em bytes e a CPU em porcentagem.

Ligar, desligar e reiniciar

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

O signal aceita start, stop, restart e kill. Prefira stop: ele desliga com calma e deixa o servidor salvar o que está em memória. O kill corta na hora, como tirar da tomada, e pode corromper o mundo ou arquivos abertos.

Enviar um comando ao console

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

O comando vai para o console exatamente como se você tivesse digitado lá. O servidor precisa estar ligado; desligado, a resposta é erro 502.

Ler e gravar arquivos

Para listar uma pasta:

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

Para ler um arquivo — a resposta é o conteúdo puro, não JSON:

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

Para gravar, o corpo da requisição é o novo conteúdo inteiro do arquivo, que é substituído:

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

Resumo dos endereços. Todos começam com https://app.redhosting.com.br/api/client/servers/SEU_SERVIDOR:

6. Exemplo: religar o servidor se ele cair

Um script em Node.js (versão 18 ou mais nova) que confere o estado e liga o servidor quando o encontra desligado. A chave vem de uma variável de ambiente, e não escrita no código — é assim que ela não vai parar no GitHub junto com o resto.

const PAINEL = 'https://app.redhosting.com.br/api/client';
const SERVIDOR = 'SEU_SERVIDOR';
const cabecalhos = {
  Authorization: `Bearer ${process.env.PAINEL_API_KEY}`,
  Accept: 'application/json',
  'Content-Type': 'application/json',
};

async function conferir() {
  const resposta = await fetch(`${PAINEL}/servers/${SERVIDOR}/resources`, { headers: cabecalhos });
  if (!resposta.ok) throw new Error(`API respondeu ${resposta.status}`);

  const { attributes } = await resposta.json();
  if (attributes.current_state === 'offline') {
    await fetch(`${PAINEL}/servers/${SERVIDOR}/power`, {
      method: 'POST',
      headers: cabecalhos,
      body: JSON.stringify({ signal: 'start' }),
    });
    console.log('Servidor estava desligado — ligando.');
  }
}

conferir().catch((erro) => console.error(erro.message));

Rodando a cada poucos minutos, por um agendamento do sistema, ele religa o servidor depois de uma queda. Não rode em intervalo curto demais: veja o limite de requisições na próxima seção.

7. Erros comuns

8. Segurança

• Uma chave por uso. Uma para o bot, outra para o script de backup. Se uma vazar, você apaga só ela e o resto continua funcionando.
• Preencha IPs Permitidos sempre que souber de onde a chave vai ser usada.
• Guarde a chave em variável de ambiente ou num arquivo .env que esteja no .gitignore, nunca dentro do código.
• Confira o "Último uso" de cada chave na aba Chave API. Uma chave que você não usa mais, mas que continua sendo usada, é uma chave que vazou.
• Para revogar, clique na lixeira ao lado da chave. A exclusão vale na hora para todas as requisições.