Saltar a contenido

Crea y usa un token de API con permisos granulares

Los tokens de API permiten que scripts, bots y tareas de CI llamen a la API de Zaroz Cloud sin guardar la contraseña de tu cuenta ni tu sesión del navegador. Cada token nuevo deniega todo por defecto: tú eliges las acciones exactas que puede ejecutar y los recursos exactos que puede tocar.

La lista completa de endpoints, cuerpos y respuestas está en la referencia OpenAPI del Kernel.

Antes de crear uno

Trata el token como una contraseña. Quien lo consiga podrá usar todos sus permisos hasta que caduque o lo revoques.

  • Crea un token distinto para cada integración.
  • Concede solo las capacidades imprescindibles.
  • Prefiere un pedido o fleet concreto a todos los recursos.
  • Añade caducidad siempre que la integración pueda rotar el secreto.
  • Nunca pongas un token en JavaScript de frontend, una app móvil, un repositorio público o un mensaje de soporte.

Tu cuenta sigue siendo el límite

Un token nunca tiene más autoridad de la que tenga su propietario en ese momento. Si más adelante se elimina una membresía de pedido o un rol de administrador, el token también pierde ese acceso de inmediato.

Crea el token

  1. Abre el panel de Zaroz Cloud.
  2. Ve a Ajustes → Seguridad → Tokens de API.
  3. Pulsa Crear token.
  4. Usa un nombre que indique su propósito, como minecraft-status-bot o gitlab-production-deploy.
  5. Elige una fecha de caducidad opcional.
  6. Añade las capacidades necesarias y selecciona un alcance para cada una.
  7. Revisa el resumen y crea el token.
  8. Cópialo de inmediato a tu gestor de contraseñas o almacén de secretos.

El token en texto plano se muestra una sola vez. Zaroz guarda un hash irreversible, así que soporte no puede recuperarlo. Si lo pierdes, revócalo y crea otro.

Para crear un token con capacidades administrativas hace falta una sesión de administrador elevada. Aun así, en cada petición se vuelven a comprobar los roles actuales del propietario.

Entiende los alcances

Cada permiso combina una capacidad exacta con un alcance:

Alcance Qué permite Buen uso
Un recurso Solo el pedido, reseller u objeto seleccionado Un bot de estado para un servidor de Minecraft
Árbol de recursos Una fleet concreta y sus hijos Automatización de fleets
Tipo de recurso Todos los recursos de un tipo a los que tengas acceso Un inventario de todos tus pedidos
Global La capacidad sin limitarla a un recurso Automatización administrativa; úsalo con cuidado

No hay comodines en los nombres. Por ejemplo, orders.read no incluye orders.server.toggle, y orders.server.toggle no da acceso a la terminal.

Autentica una petición

Envía el token en la cabecera Authorization:

Authorization: Bearer TU_TOKEN_DE_API

La URL base es:

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

No llames a la API directamente desde una web pública

El código del navegador es visible para todos los visitantes. Guarda el token en un servidor, bot, almacén de secretos de CI u otro backend de confianza.

Ejemplo en JavaScript: lee el estado de un pedido

Crea un token con orders.read, limitado al pedido que quieras consultar. Define el token y el ID como variables de entorno y ejecuta este ejemplo con Node.js 18 o superior:

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='pega-el-token-aqui'
export ZAROZ_ORDER_ID='00000000-0000-0000-0000-000000000000'
node status.mjs

Consulta Get Order Status en la referencia OpenAPI para ver todos los estados y campos posibles.

Errores que debes gestionar

  • 401 Authentication required: falta el token, está mal formado, ha caducado o fue revocado.
  • 403 Resource access forbidden: el token, su propietario o ambos carecen del permiso para ese recurso.
  • 404 Resource not found: el ID es incorrecto o el recurso se oculta deliberadamente a esta identidad.
  • 429 Rate limit exceeded: espera y reintenta con una demora exponencial.
  • 5xx: trátalo como temporal, reintenta un número limitado de veces y registra la respuesta sin registrar el token.

Rota o revoca un token

Crea primero el sustituto, actualiza la integración, comprueba que funciona y después revoca el antiguo desde Ajustes → Seguridad → Tokens de API. Los tokens con caducidad generan avisos antes de vencer y una notificación al caducar.

Las acciones hechas con tokens aparecen en los registros de auditoría con el usuario propietario y la identidad del token. Pon nombres descriptivos para que esos registros sirvan durante un incidente.

Siguientes ejemplos