API-Tokens

API-Tokens verbinden InfraNest mit Skripten, Tools und KI-Assistenten, damit du Aufgaben automatisieren kannst, die du sonst manuell in der App erledigen würdest. Dieser Artikel richtet sich an alle, die InfraNests API nutzen möchten.

#Übersicht

• Ein Token ermöglicht es externen Tools, über InfraNests API in deinem Workspace zu handeln.
• Jedes Token hat nur die Berechtigungen, die du ihm gibst, sodass du einschränken kannst, worauf es zugreifen darf.
• Tokens können auf bestimmte Adressen beschränkt, mit einem Ablaufdatum versehen und jederzeit widerrufen werden.
• Manche Aktionen auf Kontoebene erfordern immer, dass du angemeldet bist – ein Token kann sie niemals ausführen.

#Ein Token erstellen

1. Gehe zu My account → Developer und wähle New token. Das Token gehört dir und funktioniert in dem Workspace, in dem du dich beim Erstellen befindest.
2. Gib ihm einen Namen und wähle seine Berechtigungen (was es tun darf). Aktiviere Works in all my workspaces nur, wenn ein Tool tatsächlich Zugriff auf alle Workspaces benötigt, denen du angehörst.

3. Kopiere das Token jetzt – es wird nur einmal angezeigt. Danach siehst du nur noch einen Hinweis auf die letzten Zeichen.

#Berechtigungen

Berechtigungen sind granular – Lesen oder Schreiben je Bereich – plus eine schreibgeschützte Voreinstellung und Vollzugriff. Gib einem Token nur das, was es wirklich braucht.

Jeder Bereich umfasst mehr, als der Name allein vermuten lässt:

Zertifikate und Webhooks gehören zu Monitoring und sind keine eigenen Bereiche – ein Token, das eines von beidem benötigt, braucht Monitoring. Billing und das Audit-Log sind über die API immer nur lesend zugänglich, unabhängig davon, wie das Token eingerichtet ist: Ein Abonnement ändern oder eine Rechnung bezahlen kann nur eine Person tun, die in der App angemeldet ist.

#Was ein Token nicht kann

Ein Token arbeitet mit deiner Infrastruktur. Es kann dein Konto nicht ändern, selbst mit Vollzugriff, und es kann keine Einstellungen lesen, die Personen gehören oder die selbst ein Schlüssel sind: Single Sign-on, Benachrichtigungseinstellungen, gespeicherte Zahlungsdaten und Webhook-Adressen. Tokens erstellen oder widerrufen, E-Mail oder Passwort ändern, Zwei-Faktor-Authentifizierung und Passkeys, dein Konto löschen sowie Telegram, Slack oder Browser-Benachrichtigungen verbinden – all das erfordert, dass du in der App angemeldet bist. So kann ein durchgesickertes Token nicht dazu verwendet werden, dich auszusperren oder jemandem einen Weg zurück zu verschaffen.

NoteEinige Namen sind für InfraNests eigene Nutzung reserviert, zum Beispiel api. Wenn du einen solchen wählst, wirst du gebeten, einen anderen zu nehmen.

#Ein Token auf deine Adressen beschränken

1. Wenn ein Token von einem Ort mit fester Adresse verwendet wird, etwa einem CI-Runner oder einem Server, kannst du es so einrichten, dass es nur von dort funktioniert.
2. Trage unter Allowed addresses eine IP-Adresse oder einen Adressbereich pro Zeile ein, zum Beispiel 203.0.113.10 oder 203.0.113.0/24. Von jeder anderen Adresse wird das Token abgelehnt, sodass eine durchgesickerte Kopie nutzlos ist. Lasse das Feld leer, um jede Adresse zuzulassen.
3. Um die Liste später zu ändern, öffne das Menü des Tokens und wähle Limit addresses. Durch Leeren der Liste wird wieder jede Adresse zugelassen.

#Tokens verwalten

1. Sieh, wann jedes Token zuletzt verwendet wurde und wann es abläuft, und widerrufe jedes Token jederzeit.
2. Beim Erstellen eines Tokens wählst du seine Gültigkeitsdauer: 30, 90, 180 oder 365 Tage (90, sofern du nichts anderes wählst). Wir schicken dir eine E-Mail eine Woche vor Ablauf.
3. Damit es weiter funktioniert, öffne das Menü des Tokens und wähle Renew for 90 days. Das Token bleibt dabei unverändert, sodass du nichts anpassen musst, das es verwendet.

Tokens, die erstellt wurden, bevor Tokens ein Ablaufdatum hatten, zeigen Never an. Sobald ein solches Token sechs Monate alt ist, senden wir dir einmalig eine E-Mail mit dem Vorschlag, es zu erneuern, wodurch es ein Ablaufdatum erhält.

TipDie vollständige Endpoint-Referenz findest du in der App – wähle View full API documentation unter My account → Developer.

#Informiert bleiben

• Ein neues Token wird angekündigt. Wenn auf deinem Konto ein Token erstellt wird, schicken wir dir eine E-Mail, genau wie beim Hinzufügen eines Passkeys. Warst du das nicht, widerrufe es und ändere dein Passwort.
• Ungewöhnliche Aktivität wird gemeldet. Wenn ein Token plötzlich weit mehr Änderungen vornimmt als gewöhnlich, erhalten die Eigentümer deines Workspace eine Benachrichtigung, und es erscheint unter Needs you auf der Startseite. Das ist meist ein fehlerhaftes Skript oder ein Token, das jemand anderes in die Hände bekommen hat.
• Sieh, was ein Token getan hat mit View activity im Menü des Tokens: das Audit-Log, gefiltert auf dieses Token.

#In einer Sandbox ausprobieren

Wähle Create a sandbox unter My account → Developer für einen kostenlosen Übungs-Workspace mit Beispieldaten, in dem Tokens Test-Tokens sind und nichts die Außenwelt erreicht.

#Nutzung durch einen KI-Assistenten

Claude, ChatGPT, Cursor und VS Code können dein InfraNest-Konto über unseren MCP-Server lesen – frag einfach „Welche Monitore waren letzte Nacht down?“ und sie schauen es nach. Claude und ChatGPT verbinden sich ohne Token. Cursor und VS Code nutzen ein API-Token; gib ihm nur Lesezugriff auf das, was der Assistent sehen soll. Mit nur Lesezugriff kann der Assistent ausschließlich lesen. Mit Schreibzugriff auf Monitoring kann er zusätzlich Vorfälle bestätigen, Notizen hinterlassen, Monitore stummschalten, die Prüfung eines Monitors erneut ausführen und Wartungsfenster durchführen – niemals etwas anderes – und er sieht niemals Geheimnisse wie Domain-Transfer-Codes.

#Ratenbegrenzungen

Jedes Token kann bis zu 300 Anfragen pro Minute stellen, davon bis zu 60 Änderungen (Erstellen, Bearbeiten oder Löschen von etwas). Änderungen sind zudem auf 1.000 pro Stunde begrenzt, sodass ein Skript, das den ganzen Tag läuft, nicht versehentlich alles ändern kann. Dein Tarif kann andere Werte vorsehen. Überschreitet ein Token das Limit, erhält es eine Antwort „try again shortly“ mit der Angabe, wie viele Sekunden zu warten ist. Lesevorgänge funktionieren weiter, solange nur das Änderungslimit erreicht ist, und das Limit eines Tokens bremst niemals ein anderes aus.

Einige Aktionen haben zudem ein eigenes Limit pro Workspace, um die Plattform zu schützen, etwa manuelle Synchronisierungen und „check now“.