Skip to content

Create and use a fine-grained API token

API tokens let scripts, bots, and CI jobs call the Zaroz Cloud API without storing your account password or browser session. Every new token is deny-by-default: you choose the exact actions it can perform and the exact resources it can touch.

The complete list of endpoints, request bodies, and response schemas lives in the Kernel OpenAPI reference.

Before you create one

Treat a token like a password. Anyone who gets it can use every permission assigned to it until it expires or you revoke it.

  • Create a separate token for each integration.
  • Grant only the capabilities the integration needs.
  • Prefer one specific order or fleet over all resources.
  • Add an expiry date whenever the integration can rotate its secret.
  • Never put a token in frontend JavaScript, a mobile app, a public repository, or a support message.

Your account remains the upper limit

A token never has more authority than its owner currently has. If an order membership or administrator role is removed later, the token loses that access immediately too.

Create the token

  1. Open the Zaroz Cloud dashboard.
  2. Go to Settings → Security → API tokens.
  3. Select Create token.
  4. Give it a name that identifies its purpose, such as minecraft-status-bot or gitlab-production-deploy.
  5. Choose an optional expiry date.
  6. Add the required capabilities and choose a scope for each one.
  7. Review the summary and create the token.
  8. Copy the token immediately into your password manager or secret store.

The plaintext token is shown only once. Zaroz stores a one-way hash, so support cannot recover it later. If you lose it, revoke it and create a replacement.

Creating a token with administrator capabilities requires an elevated administrator session. Those capabilities are still checked against the owner's current roles on every request.

Understand scopes

Each grant combines one exact capability with one scope:

Scope What it allows Good use
One resource Only the selected order, reseller, or other object A status bot for one Minecraft server
Resource tree A selected fleet and its children Fleet automation
Resource type Every resource of one type available to you An account-wide order inventory
Global The capability regardless of resource Administrative automation; use sparingly

There are no wildcard capability names. For example, orders.read does not imply orders.server.toggle, and orders.server.toggle does not imply terminal access.

Authenticate a request

Send the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

The API base URL is:

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

Do not call the API directly from a public website

Browser code is visible to every visitor. Keep the token in a server, bot, CI secret store, or another trusted backend.

JavaScript example: read an order's runtime status

Create a token with orders.read, scoped to the order you want to inspect. Set the token and order ID as environment variables, then run this example with Node.js 18 or newer:

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='paste-the-token-here'
export ZAROZ_ORDER_ID='00000000-0000-0000-0000-000000000000'
node status.mjs

See Get Order Status in the OpenAPI reference for every possible state and response field.

Errors you should handle

  • 401 Authentication required: the token is missing, malformed, expired, or revoked.
  • 403 Resource access forbidden: the token, its owner, or both lack the capability for that resource.
  • 404 Resource not found: the ID is wrong, or the resource is deliberately hidden from this identity.
  • 429 Rate limit exceeded: wait and retry with exponential backoff.
  • 5xx: treat it as temporary, retry a limited number of times, and log the response without logging the token.

Rotate or revoke a token

Create the replacement first, update the integration, verify it works, and then revoke the old token from Settings → Security → API tokens. Tokens with an expiry date trigger reminders before expiry and a notification when they expire.

Token-backed actions appear in audit logs with both the owning user and the token identity. Give tokens descriptive names so those records remain useful during an incident.

Next examples