API & Automatisierung

KiroCloud bietet eine moderne, REST-basierte API an, mit der du externe Tools, Bots oder CI/CD-Pipelines an dein Dashboard anbinden kannst. Alle Anfragen erfordern eine sichere Authentifizierung via API-Schlüssel.

1. API-Schlüssel erstellen

API-Schlüssel werden direkt in deinem Benutzer-Dashboard generiert:

1. Navigiere im Dashboard zu Einstellungen > Entwickler & API-Schlüssel.
2. Klicke auf Neuen API-Schlüssel erstellen.
3. Vergib einen eindeutigen Namen (z. B. "GitHub Actions Deployment").
4. Bestimme die Gültigkeitsdauer (in Tagen).
5. Wähle die benötigten Berechtigungen (Scopes). Vergib stets nur die Rechte, die für den jeweiligen Anwendungsfall zwingend nötig sind (Prinzip der geringsten Privilegien / Least Privilege).
6. Klicke auf Erstellen und kopiere den Token sofort. Er wird dir danach nie wieder im Klartext angezeigt!

!WARNING Teile deinen API-Schlüssel niemals öffentlich. Sollte ein Schlüssel kompromittiert werden, lösche (revoke) ihn umgehend im Dashboard.

2. Authentifizierung

Um sich bei der KiroCloud-API zu authentifizieren, musst du den API-Schlüssel im Authorization-Header als Bearer-Token mitsenden.

Authorization: Bearer kiro_sec_DEIN_SCHLUESSEL

3. Berechtigungen (Scopes)

Je nachdem, was du automatisieren willst, benötigt dein API-Schlüssel spezifische Scopes:

• bots:read - Erlaubt das Auslesen des Status und der Metriken deiner eigenen Discord Bots.
• bots:write - Erlaubt Steuerungsbefehle (Starten, Stoppen, Neustarten) und das Senden von Embeds.
• tickets:read - Erlaubt das Einsehen deiner eigenen Support-Tickets.
• tickets:write - Erlaubt das Eröffnen neuer Support-Tickets und Antworten.
• servers:read - Erlaubt die Abfrage des Serverstatus für verknüpfte Minecraft-Server.

!TIP Ein API Key mit dem Scope bots:write kann beispielsweise nach einem erfolgreichen GitHub Actions Build automatisch einen Neustart des Bots über POST /api/v1/bots/:id/restart auslösen.

4. Beispiel-Aufrufe

cURL

curl -X GET "https://api.kirocloud.de/api/v1/bots" \
  -H "Authorization: Bearer kiro_sec_YOUR_API_KEY" \
  -H "Accept: application/json"

Node.js / JavaScript (Fetch)

const response = await fetch("https://api.kirocloud.de/api/v1/bots", {
  method: "GET",
  headers: {
    "Authorization": "Bearer kiro_sec_YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});
const data = await response.json();
console.log(data);

Python (Requests)

import requests

url = "https://api.kirocloud.de/api/v1/bots"
headers = {
    "Authorization": "Bearer kiro_sec_YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

5. Fehlerbehebung