Zum Inhalt

Ein fein abgestuftes API-Token erstellen und verwenden

Mit API-Tokens können Skripte, Bots und CI-Jobs die Zaroz-Cloud-API aufrufen, ohne dein Kontopasswort oder deine Browser-Sitzung zu speichern. Jedes neue Token verweigert zunächst alles: Du wählst die genauen Aktionen und Ressourcen selbst aus.

Alle Endpunkte, Request-Bodys und Antwortschemas findest du in der Kernel-OpenAPI-Referenz.

Bevor du ein Token erstellst

Behandle ein Token wie ein Passwort. Wer es besitzt, kann bis zum Ablauf oder Widerruf alle zugewiesenen Rechte verwenden.

  • Erstelle für jede Integration ein eigenes Token.
  • Vergib nur die wirklich benötigten Fähigkeiten.
  • Beschränke es lieber auf eine Bestellung oder Fleet als auf alle Ressourcen.
  • Setze ein Ablaufdatum, wenn die Integration ihr Secret rotieren kann.
  • Lege Tokens nie in Frontend-JavaScript, mobilen Apps, öffentlichen Repositories oder Support-Nachrichten ab.

Dein Konto bleibt die Obergrenze

Ein Token hat nie mehr Rechte als sein Besitzer aktuell. Wird später eine Bestellmitgliedschaft oder Admin-Rolle entfernt, verliert das Token diesen Zugriff sofort ebenfalls.

Token erstellen

  1. Öffne das Zaroz-Cloud-Dashboard.
  2. Gehe zu Einstellungen → Sicherheit → API-Tokens.
  3. Wähle Token erstellen.
  4. Vergib einen aussagekräftigen Namen wie minecraft-status-bot oder gitlab-production-deploy.
  5. Wähle optional ein Ablaufdatum.
  6. Füge die benötigten Fähigkeiten hinzu und wähle für jede einen Geltungsbereich.
  7. Prüfe die Zusammenfassung und erstelle das Token.
  8. Kopiere es sofort in deinen Passwortmanager oder Secret Store.

Das Klartext-Token wird nur einmal angezeigt. Zaroz speichert lediglich einen Einweg-Hash; der Support kann es später nicht wiederherstellen. Wenn du es verlierst, widerrufe es und erstelle Ersatz.

Für ein Token mit Admin-Fähigkeiten brauchst du eine erhöhte Admin-Sitzung. Die aktuellen Rollen des Besitzers werden trotzdem bei jeder Anfrage erneut geprüft.

Geltungsbereiche verstehen

Jede Freigabe verbindet eine genaue Fähigkeit mit einem Geltungsbereich:

Bereich Erlaubt Sinnvoll für
Eine Ressource Nur die ausgewählte Bestellung oder ein anderes Objekt Status-Bot für einen Minecraft-Server
Ressourcenbaum Eine Fleet und ihre untergeordneten Bestellungen Fleet-Automatisierung
Ressourcentyp Alle für dich verfügbaren Ressourcen eines Typs Bestellinventar für das ganze Konto
Global Die Fähigkeit unabhängig von einer Ressource Admin-Automatisierung; sparsam einsetzen

Es gibt keine Platzhalter in Fähigkeiten. orders.read schließt beispielsweise orders.server.toggle nicht ein, und orders.server.toggle gewährt keinen Terminalzugriff.

Anfrage authentifizieren

Sende das Token im Authorization-Header:

Authorization: Bearer DEIN_API_TOKEN

Die API-Basis-URL lautet:

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

Rufe die API nicht direkt aus einer öffentlichen Website auf

Browser-Code ist für jeden Besucher sichtbar. Bewahre das Token auf einem Server, in einem Bot, im CI Secret Store oder in einem anderen vertrauenswürdigen Backend auf.

JavaScript-Beispiel: Laufzeitstatus lesen

Erstelle ein Token mit orders.read, das auf die gewünschte Bestellung begrenzt ist. Setze Token und Bestell-ID als Umgebungsvariablen und starte das Beispiel mit Node.js 18 oder neuer:

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

Unter Get Order Status in der OpenAPI-Referenz findest du alle möglichen Zustände und Felder.

Fehler behandeln

  • 401 Authentication required: Token fehlt, ist fehlerhaft, abgelaufen oder widerrufen.
  • 403 Resource access forbidden: Token, Besitzer oder beide haben nicht die benötigte Berechtigung.
  • 404 Resource not found: ID ist falsch oder die Ressource wird für diese Identität verborgen.
  • 429 Rate limit exceeded: Warte und versuche es mit exponentiell steigender Verzögerung erneut.
  • 5xx: Behandle den Fehler als temporär, begrenze Wiederholungen und protokolliere niemals das Token.

Token rotieren oder widerrufen

Erstelle zuerst Ersatz, aktualisiere die Integration, prüfe sie und widerrufe dann das alte Token unter Einstellungen → Sicherheit → API-Tokens. Für Tokens mit Ablaufdatum werden Erinnerungen und beim Ablauf eine Benachrichtigung verschickt.

Aktionen erscheinen im Audit-Log mit Besitzer und Token-Identität. Aussagekräftige Namen machen diese Einträge bei einem Vorfall deutlich nützlicher.

Weitere Beispiele