Pular para o conteúdo
Documentação

API do miniCP: visão geral e tokens

Como ativar a API do miniCP, a diferença entre o token de leitura e o de escrita e como restringir o acesso por IP.

R Regis Manze 20/11/2026 4 min de leitura

A API do miniCP deixa sistemas externos (ERP, monitoramento, suporte, scripts de ativação) consultar usuários e domínios e, com o token de escrita, criar domínios e publicá-los no HAProxy.

A API fica em /api/v1 no mesmo endereço do painel. Ela vem desligada: só responde depois que você gera um token.

Tokens de leitura e de escrita

Existem dois tokens, cada um com uma finalidade.

Token O que permite Quando usar
Leitura Só consultas: usuários, domínios, situação no HAProxy, andamento de jobs. Nas variáveis de ambiente dos domínios (env), vê só os nomes, sem os valores. Painéis de monitoramento, ERP, ferramentas de suporte.
Escrita Tudo o que o de leitura faz (inclusive os valores de env), mais criar, alterar e remover domínios e publicar ou tirar domínios do HAProxy. Automação de ativação de clientes, em sistemas de confiança.

Com o token de leitura, uma operação de escrita responde 403 com a mensagem token somente leitura: use o token de escrita.

Atenção: os tokens da API são diferentes do token do cluster (usado pelo CmCP). Um não substitui o outro.

Versão mínima

Recurso Versão do miniCP
Consultas (token de leitura) 2.55.0
Escrita: domínios e HAProxy 2.63.0
Publicar um alias no HAProxy 2.63.1
Token de leitura vê só os nomes de env 2.66.0

Recomendamos 2.63.1 ou mais nova para usar a escrita. A versão do painel volta em toda resposta, no campo panel_version.

Gerar os tokens

  1. Entre no miniCP como administrador.
  2. Abra Configurações e fique na aba Geral.
  3. Na seção API, clique em Gerar token (token de leitura).
  4. Se precisar de escrita, clique em Gerar token de escrita e confirme.
  5. Copie o token do campo correspondente e guarde num cofre de senhas.

Para trocar um token, clique em Regerar. O token anterior para de funcionar na hora. Para desligar, clique em Remover: sem token de leitura nem de escrita, a API não responde a ninguém.

Restringir por IP

Na mesma seção há o campo de IPs permitidos.

  1. Informe os IPs ou redes que podem usar a API, separados por vírgula ou espaço. Exemplo: 203.0.113.10, 198.51.100.0/24.
  2. Clique em Salvar IPs.

Com a lista preenchida, chamadas de outros endereços recebem 403 com ip nao permitido, mesmo com token válido. Lista vazia libera qualquer IP (com token). A lista vale para os dois tokens.

Com o painel atrás do HAProxy, o IP de quem chama é lido do fim do cabeçalho X-Forwarded-For (o valor acrescentado pelo balanceador). Um cabeçalho forjado por quem chama não burla a lista.

Dica: preencha a lista sempre que gerar o token de escrita. Quem tem esse token cria e remove domínios.

Como autenticar

Envie o token no cabeçalho Authorization:

MINICP=https://painel.exemplo.com.br:5000
TOKEN=seu_token

curl -s -H "Authorization: Bearer $TOKEN" "$MINICP/api/v1/"

O cabeçalho X-API-Token: seu_token também é aceito. O token não é aceito na URL, para não ficar gravado em logs.

A chamada a /api/v1/ devolve a lista de endpoints disponíveis.

Formato das respostas

Todas as respostas são JSON. As de sucesso têm "ok": true e estes campos fixos:

Campo Conteúdo
ok true em caso de sucesso.
server Nome do servidor que respondeu.
panel_version Versão do miniCP.
generated Data e hora da resposta.

Os erros têm "ok": false e a mensagem em português no campo error. Veja a lista em API: erros e boas práticas.

Segurança

  • Bloqueio por força bruta: cada chamada com token errado conta como tentativa de login falha. Cinco falhas em 15 minutos bloqueiam o IP por 15 minutos (resposta 429). As falhas do login no painel, da API e do token do cluster somam na mesma contagem, e o bloqueio vale para os três.
  • Auditoria: toda alteração feita pela API fica em Auditoria com o usuário api e o IP de origem.
  • Regerar em caso de vazamento: se um token aparecer em log, chamado ou repositório, clique em Regerar e atualize o sistema que o usa.
  • Use HTTPS: o token vai no cabeçalho de cada chamada. Acesse o painel por HTTPS.
  • /api/status não faz parte da API: esse endereço alimenta o Dashboard e exige sessão de administrador no painel. Não use em integrações; use os endpoints de /api/v1.
Copiar para usar com IA

Este artigo foi útil?

Que bom! O que ajudou mais? O que faltou nesta página?

Opcional — seu voto já foi registrado.

Obrigado pelo seu feedback!