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

> Crie uma chave de API na sua conta do painel e use-a para ligar, desligar, reiniciar, enviar comandos e mexer em arquivos do servidor por script. Recurso experimental, sem suporte da equipe.

- Guia da base de conhecimento da RedHosting — categoria: Outros
- Página HTML: https://redhosting.com.br/base-de-conhecimento/como-criar-uma-chave-de-api-e-gerenciar-seu-servidor-pela-api-do-painel
- Publicado em: 2026-09-24 · Idioma: pt-BR

🧪**Recurso experimental — sem suporte**: A API do painel está liberada para quem quiser automatizar o próprio servidor, mas **a RedHosting não presta suporte a ela**. A equipe não ajuda a montar scripts, não depura integrações e não responde pelo que um script executar no seu servidor — inclusive desligar, apagar arquivos ou enviar comandos por engano. O comportamento da API pode mudar sem aviso. O suporte continua cobrindo o serviço em si: servidor fora do ar, painel, rede e cobrança.

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.

  ⚠️**Trate a chave como a sua senha**: Quem tiver a chave controla todos os seus servidores, sem precisar da senha nem da verificação em duas etapas. Nunca publique a chave no GitHub, num print ou num canal do Discord.

## 2. Criando a chave

1. Entre no painel em [app.redhosting.com.br](https://app.redhosting.com.br).
2. No menu lateral, clique em **Conta** — ou abra direto [app.redhosting.com.br/account](https://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.

  💡**Dica**: Se o script vai rodar numa VPS ou num servidor de bot da RedHosting, preencha IPs Permitidos com o IP dele. Assim, mesmo que a chave vaze, ela não funciona de nenhum outro lugar.

## 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`:

    AçãoMétodoEndereço

    Estado e consumoGET`/resources`
    Ligar, desligar, reiniciarPOST`/power`
    Comando no consolePOST`/command`
    Listar pastaGET`/files/list?directory=/`
    Ler arquivoGET`/files/contents?file=/caminho`
    Gravar arquivoPOST`/files/write?file=/caminho`
    Listar backupsGET`/backups`

## 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.

  💡**Dica**: Antes de automatizar o religamento, descubra por que o servidor está caindo. Um servidor que cai por falta de memória vai cair de novo logo depois de ligar, e o script só esconde o problema. O guia [Meu serviço está fora do ar: como descobrir a causa](/base-de-conhecimento/meu-servico-esta-fora-do-ar-como-descobrir-a-causa) ajuda nisso.

## 7. Erros comuns

    RespostaO que significaO que fazer

    **401**A chave não foi aceita.Confira se copiou a chave inteira, com o `ptlc_`, e se o cabeçalho é `Authorization: Bearer`. Uma chave apagada no painel para de funcionar na hora.
    **403**A chave funciona, mas não aqui.O IP de onde a requisição saiu não está em IPs Permitidos, ou sua conta é subusuária do servidor sem a permissão dessa ação.
    **404**Servidor ou arquivo não encontrado.Confira o identificador de 8 caracteres e o caminho do arquivo, que começa com `/`.
    **409**O servidor não pode fazer isso agora.Ele está instalando, sendo transferido ou suspenso. Espere terminar.
    **429**Requisições demais.O painel aceita até 256 requisições por minuto por conta. Espace as chamadas.
    **502**O servidor precisa estar ligado.Acontece ao enviar comando com o servidor desligado. Ligue antes.

## 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.

  Antes de colocar o script para rodar

    ✓A chave tem uma descrição que diz para que ela serve.

    ✓IPs Permitidos está preenchido com o IP da máquina que vai usar a chave.

    ✓A chave está numa variável de ambiente, fora do código e fora do Git.

    ✓Você testou a chave com a listagem de servidores e recebeu a sua lista.

    ✓O script usa `stop`, e não `kill`, para desligar.

    ✓Você sabe que a API é experimental e que o suporte não ajuda com o script.

## Perguntas frequentes

**A RedHosting dá suporte à API do painel?**

Não. A API é um recurso experimental, oferecido como está: a equipe não ajuda a montar scripts nem depura integrações, e não responde pelo que um script executar no servidor. O suporte continua cobrindo o serviço em si — servidor fora do ar, painel, rede e cobrança.

**Onde crio a chave de API?**

No painel, em **Conta** → aba **Chave API**, no quadro do fim da página. Preencha a descrição, os IPs permitidos e clique em Criar.

**Perdi a chave. Consigo ver de novo?**

Não. A chave só aparece uma vez, na hora da criação. Apague a antiga pela lixeira e crie outra.

**A chave dá acesso a quais servidores?**

A todos os servidores da sua conta, com as mesmas permissões que você tem no painel. Não existe chave limitada a um servidor só — por isso vale preencher IPs Permitidos e usar uma chave por aplicação.

**Onde encontro o identificador do servidor?**

Na barra de endereço, ao abrir o servidor no painel: é o código de 8 caracteres depois de `/server/`.

**Posso usar a chave num bot de Discord?**

Pode, guardando a chave numa variável de ambiente e nunca no código. E restrinja no bot quem pode acionar os comandos: um comando de desligar aberto a todo o servidor do Discord é um botão de desligar aberto a qualquer um.

**Existe limite de requisições?**

Sim, 256 por minuto. Acima disso a API responde 429 até o minuto virar.

## Navegação — Outros (artigo 9 de 9)

- Artigo anterior: Bem-vindo ao Git da RedHosting — https://redhosting.com.br/base-de-conhecimento/bem-vindo-ao-git-da-redhosting
- Voltar à base de conhecimento: https://redhosting.com.br/base-de-conhecimento

---

Precisa de ajuda com este passo a passo? Suporte 24/7 da RedHosting:
suporte@redhosting.com.br · WhatsApp +55 11 98833-3902 · https://redhosting.com.br/discord

Outros guias: https://redhosting.com.br/md/base-de-conhecimento.md