Ir para o conteúdo

Criar e usar um token de API com permissões detalhadas

Os tokens de API permitem que scripts, bots e tarefas de CI chamem a API da Zaroz Cloud sem guardar a palavra-passe da tua conta ou a sessão do navegador. Cada token novo nega tudo por omissão: escolhes as ações e os recursos exatos a que pode aceder.

A lista completa de endpoints, pedidos e respostas está na referência OpenAPI do Kernel.

Antes de criares um

Trata o token como uma palavra-passe. Quem o obtiver pode usar todas as permissões atribuídas até ele expirar ou ser revogado.

  • Cria um token separado para cada integração.
  • Atribui apenas as capacidades indispensáveis.
  • Prefere uma encomenda ou fleet específica a todos os recursos.
  • Define uma expiração sempre que a integração consiga rodar o segredo.
  • Nunca coloques o token em JavaScript de frontend, aplicações móveis, repositórios públicos ou mensagens de suporte.

A tua conta continua a ser o limite

Um token nunca tem mais autoridade do que o proprietário tem nesse momento. Se uma associação a uma encomenda ou um cargo administrativo for removido, o token também perde esse acesso imediatamente.

Criar o token

  1. Abre o painel da Zaroz Cloud.
  2. Vai a Definições → Segurança → Tokens de API.
  3. Seleciona Criar token.
  4. Dá-lhe um nome que identifique o objetivo, como minecraft-status-bot ou gitlab-production-deploy.
  5. Escolhe uma data de expiração opcional.
  6. Adiciona as capacidades necessárias e um âmbito para cada uma.
  7. Revê o resumo e cria o token.
  8. Copia-o imediatamente para o gestor de palavras-passe ou cofre de segredos.

O token em texto simples aparece uma única vez. A Zaroz guarda apenas um hash irreversível, por isso o suporte não o pode recuperar. Se o perderes, revoga-o e cria outro.

Criar um token com capacidades administrativas exige uma sessão de administrador elevada. Mesmo assim, os cargos atuais do proprietário são novamente verificados em cada pedido.

Compreender os âmbitos

Cada autorização combina uma capacidade exata com um âmbito:

Âmbito O que permite Bom uso
Um recurso Apenas a encomenda ou objeto selecionado Bot de estado para um servidor Minecraft
Árvore de recursos Uma fleet e os respetivos filhos Automatização de fleets
Tipo de recurso Todos os recursos de um tipo disponíveis para ti Inventário de todas as encomendas
Global A capacidade sem limite de recurso Automatização administrativa; usa com cuidado

Não existem curingas nas capacidades. Por exemplo, orders.read não inclui orders.server.toggle, e orders.server.toggle não dá acesso ao terminal.

Autenticar um pedido

Envia o token no cabeçalho Authorization:

Authorization: Bearer O_TEU_TOKEN_DE_API

O URL base é:

https://kernel.zaroz.cloud/api/v1

Não chames a API diretamente a partir de um site público

O código do navegador é visível para todos os visitantes. Guarda o token num servidor, bot, cofre de CI ou outro backend de confiança.

Exemplo JavaScript: ler o estado de uma encomenda

Cria um token com orders.read, limitado à encomenda pretendida. Define o token e o ID como variáveis de ambiente e executa este exemplo com Node.js 18 ou mais recente:

status.mjs
const API_BASE = "https://kernel.zaroz.cloud/api/v1";
const token = process.env.ZAROZ_API_TOKEN;
const orderId = process.env.ZAROZ_ORDER_ID;

if (!token || !orderId) {
  throw new Error("Set ZAROZ_API_TOKEN and ZAROZ_ORDER_ID first");
}

async function zaroz(path, options = {}) {
  const response = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
      ...options.headers,
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Zaroz API ${response.status}: ${body}`);
  }

  return response.json();
}

const status = await zaroz(`/orders/${orderId}/status`);
const primary = status.provisions.find((provision) => provision.is_primary);

console.log(`Order state: ${status.state}`);
console.log(`Primary service: ${primary?.status ?? "not provisioned"}`);

if (primary?.external_ip && primary?.external_port) {
  console.log(`Address: ${primary.external_ip}:${primary.external_port}`);
}

export ZAROZ_API_TOKEN='cola-o-token-aqui'
export ZAROZ_ORDER_ID='00000000-0000-0000-0000-000000000000'
node status.mjs

Consulta Get Order Status na referência OpenAPI para todos os estados e campos possíveis.

Erros que deves tratar

  • 401 Authentication required: o token está ausente, malformado, expirado ou revogado.
  • 403 Resource access forbidden: o token, o proprietário ou ambos não têm a permissão necessária.
  • 404 Resource not found: o ID está errado ou o recurso está deliberadamente oculto desta identidade.
  • 429 Rate limit exceeded: espera e repete com atraso exponencial.
  • 5xx: trata como temporário, limita as tentativas e nunca registes o token.

Rodar ou revogar um token

Cria primeiro o substituto, atualiza a integração, confirma que funciona e só depois revoga o antigo em Definições → Segurança → Tokens de API. Os tokens com expiração geram lembretes antes da data e uma notificação quando expiram.

As ações aparecem nos registos de auditoria com o proprietário e a identidade do token. Nomes descritivos tornam esses registos muito mais úteis durante um incidente.

Exemplos seguintes