API-Tokens
API-Tokens sind persönliche Zugriffstokens für die smoxy-API. Sie authentifizieren Anfragen und ermöglichen die Automatisierung von Aufgaben - etwa das Konfigurieren von Zonen, das Verwalten von Einstellungen oder das Abrufen von Daten - ohne Anmeldung über das Dashboard.
Ein Token ist wie ein Passwort zu behandeln: Wer es besitzt, kann im eigenen Namen handeln. Tokens werden im Account-Bereich unter API-Tokens verwaltet.
WARNING
Tokens geheim halten. Ein Token gewährt im Rahmen seines Geltungsbereichs denselben Zugriff wie das Konto selbst. Tokens dürfen niemals in die Versionsverwaltung eingecheckt, in geteilte Dokumente eingefügt oder in clientseitigem Code offengelegt werden.
Token erstellen
Im Bereich Account → API-Tokens lässt sich ein neues Token erstellen. Anzugeben sind:
| Feld | Beschreibung |
|---|---|
| Name | Eine Bezeichnung zur späteren Identifikation, z. B. CI/CD-Pipeline. Sie hat keinen Einfluss auf den Zugriff und dient nur der Unterscheidung. |
| Ablauf | Ein optionales Ablaufdatum. Bleibt das Feld leer, läuft das Token nie ab. |
| Organisationszugriff | Entweder Alle Organisationen (jede Organisation mit Mitgliedschaft) oder Bestimmte Organisationen (nur die hinzugefügten). |
Mit der Auswahl Bestimmte Organisationen erscheint ein Suchfeld zum Hinzufügen der Organisationen, auf die das Token zugreifen darf.
WARNING
Token sofort kopieren. Der Token-Wert wird nur einmal angezeigt, direkt nach der Erstellung. Sobald der Dialog geschlossen ist, lässt er sich nicht erneut abrufen - bei Verlust muss ein neues Token erstellt werden.
Tokens verwalten
Die Liste API-Tokens zeigt alle erstellten Tokens samt:
- Erstellt - wann das Token generiert wurde.
- Zuletzt verwendet - wann das Token zuletzt eine Anfrage authentifiziert hat, oder Nie verwendet, falls es noch nicht genutzt wurde.
- Läuft ab - das Ablaufdatum, oder Läuft nie ab, falls keines festgelegt wurde.
Token widerrufen
Ein Token kann jederzeit widerrufen werden. Ein widerrufenes Token funktioniert sofort nicht mehr, und jede Integration, die es verwendet, wird bei der nächsten Anfrage abgewiesen. Ein Token sollte widerrufen werden, sobald es nicht mehr benötigt wird oder ein Verdacht auf Offenlegung besteht.
Legacy-API-Tokens
Manche Konten verfügen möglicherweise noch über Legacy-API-Tokens - ein älterer Token-Typ, der veraltet und weniger sicher ist als persönliche Zugriffstokens.
Vorhandene Legacy-Tokens sollten zu persönlichen Zugriffstokens rotiert werden:
- Ein neues persönliches Zugriffstoken mit dem passenden Organisationszugriff erstellen.
- Die Integrationen auf das neue Token umstellen.
- Das Legacy-Token löschen, sobald nichts mehr davon abhängt.
WARNING
Das Löschen eines Legacy-Tokens wirkt sofort. Jede Integration, die dieses Token noch verwendet, funktioniert unmittelbar nach dem Löschen nicht mehr. Vorab ist sicherzustellen, dass alle Integrationen umgestellt wurden.
Token verwenden
Die öffentliche smoxy-API ist unter https://api.smoxy.eu erreichbar. Jede Anfrage wird authentifiziert, indem das Token im HTTP-Header X-API-TOKEN mitgesendet wird:
curl -H "X-API-TOKEN: <token>" https://api.smoxy.eu/api/zonesDie vollständige Liste der Endpunkte, Anfrageparameter und Antwortformate findet sich in der API-Referenz.
Best Practices
- Tokens sicher speichern. Tokens gehören in einen Secrets-Manager oder in Umgebungsvariablen, niemals in die Versionsverwaltung oder in Klartext.
- Auf bestimmte Organisationen beschränken. Benötigt ein Token nur Zugriff auf eine Organisation, sollte es auf diese beschränkt werden, statt Alle Organisationen zu gewähren.
- Ablauf festlegen. Ablaufende Tokens begrenzen, wie lange ein offengelegtes Token nutzbar bleibt. Wo eine automatische Rotation möglich ist, empfehlen sich kurze Laufzeiten.
- Regelmäßig rotieren und widerrufen. Tokens regelmäßig ersetzen und alle widerrufen, die ungenutzt, nicht mehr nötig oder möglicherweise offengelegt sind.