API-Schlüssel
So erstellen, verwalten und verwenden Sie API-Schlüssel für den programmatischen Zugriff auf die VergeOS-REST-API, einschließlich Authentifizierung, IP-Zugriffskontrollen, Ablaufdatumseinstellungen und Sicherheits-Best Practices.
Übersicht
API-Schlüssel bieten Authentifizierung für den programmgesteuerten Zugriff auf die VergeOS REST API und integrierte Dienste. Jeder API-Schlüssel ist mit einem bestimmten Benutzerkonto verknüpft und übernimmt die Berechtigungen und Zugriffsebenen dieses Benutzers. Dadurch können Anwendungen, Skripte und Drittanbieter-Tools mit VergeOS interagieren, ohne dass interaktive Anmeldesitzungen erforderlich sind.
Häufige Verwendungszwecke für API-Schlüssel:
Authentifizierung der REST-API für Automatisierung und Integration
Zugriff auf den OpenAI-kompatiblen KI-Router
Integration von Drittanbieter-Tools (Monitoring, Orchestrierung, IaC-Tools)
Authentifizierung für CI/CD-Pipelines
API-Schlüssel-Authentifizierung verstehen
API-Schlüssel in VergeOS funktionieren als Bearer-Tokens im HTTP-Authorization-Header. Im Gegensatz zu Sitzungstokens, die während der UI-Anmeldung erzeugt werden (und nach Inaktivität ablaufen), bleiben API-Schlüssel bis zu ihrem konfigurierten Ablaufdatum oder ihrer manuellen Löschung gültig.
Jeder API-Schlüssel übernimmt alle Berechtigungen von seinem zugehörigen Benutzerkonto. Ein für einen Mandantenadministrator erstellter API-Schlüssel verfügt über die Berechtigungen eines Mandantenadministrators, während ein Schlüssel für einen Systemadministrator systemweiten Zugriff hat.
Einen API-Schlüssel erstellen
Zur API-Schlüssel-Verwaltung navigieren
Navigieren Sie im Hauptmenü von VergeOS zu System > Benutzer
Wählen Sie das Benutzerkonto aus, dem der API-Schlüssel gehören soll
Klicken Sie im Benutzer-Dashboard auf das API-Schlüssel -Widget, um vorhandene Schlüssel anzuzeigen
Der Bereich „API-Schlüssel“ zeigt eine Tabelle mit:
Namen: Beschreibender Bezeichner für jeden Schlüssel
Letzte Anmeldung: Zeitstempel der letzten Authentifizierung
Letzte Anmelde-IP: Quell-IP der letzten Authentifizierung
Läuft ab: Verbleibende Tage bis zum Ablauf
Erstellt: Zeitstempel der Schlüsselerstellung
Neuen API-Schlüssel erstellen
Klicken Sie + Neuer API-Schlüssel am unteren Rand der Tabelle „API-Schlüssel“
Das Formular öffnet sich mit zwei Bereichen: API-Schlüssel (links) und Zugriff (rechts)
API-Schlüssel-Einstellungen konfigurieren
Namen (Erforderlich) Geben Sie einen beschreibenden Bezeichner für den API-Schlüssel ein. Eine klare Benennung hilft bei der Nachverfolgung und Schlüsselverwaltung.
Beschreibung (Optional) Fügen Sie zusätzlichen Kontext zum Zweck des Schlüssels, zum Anforderer oder zu zugehörigen Systemen hinzu.
Ablaufart Wählen Sie, wie die Gültigkeitsdauer des Schlüssels verwaltet wird:
Datum festlegen: Legen Sie ein bestimmtes Ablaufdatum fest (für die Sicherheit empfohlen)
Nie ablaufen: Erstellen Sie einen dauerhaften Schlüssel (mit Vorsicht verwenden)
Läuft ab (Wenn „Datum festlegen“ ausgewählt ist) Verwenden Sie den Datum-/Zeitauswähler, um festzulegen, wann der Schlüssel ablaufen soll. Übliche Ablaufzeiträume sind 30, 60 oder 90 Tage.
Zugriffskontrollen konfigurieren
IP-Zulassungsliste Beschränken Sie den API-Schlüssel auf bestimmte IP-Adressen oder CIDR-Bereiche. Nur aufgeführte Adressen können sich mit diesem Schlüssel authentifizieren.
Klicken Sie auf die + (Plus) Symbol zum Hinzufügen eines Eintrags
Geben Sie eine IP-Adresse ein (z. B.,
192.168.1.100) oder einen CIDR-Bereich (z. B.,192.168.1.0/24)Aktivieren Sie das Kontrollkästchen, um den Eintrag zu aktivieren
Fügen Sie bei Bedarf weitere Einträge hinzu
IP-Sperrliste Blockieren Sie bestimmte IP-Adressen oder Bereiche für die Verwendung dieses Schlüssels, während alle anderen zugelassen werden.
Klicken Sie auf die + (Plus) Symbol zum Hinzufügen eines Eintrags
Geben Sie die zu blockierende IP-Adresse oder den CIDR-Bereich ein
Aktivieren Sie das Kontrollkästchen, um den Eintrag zu aktivieren
API-Schlüssel speichern und abrufen
Überprüfen Sie alle Einstellungen auf Genauigkeit
Klicken Sie Senden , um den API-Schlüssel zu generieren
Ein Popup zeigt den generierten API-Schlüssel mit zwei Optionen an:
Kopieren: Klicken Sie, um die vollständige Schlüsselzeichenfolge in die Zwischenablage zu kopieren
Speichern: Klicken Sie, um den Schlüssel als
.PAK-Datei für geschützte API-Schlüssel herunterzuladen
Einmalige Anzeige
Der vollständige API-Schlüssel wird nur bei der Erstellung angezeigt. Sobald Sie dieses Popup schließen, kann der vollständige Schlüssel nicht mehr abgerufen werden. Wenn Sie den Schlüssel verlieren, müssen Sie ihn löschen und einen neuen erstellen.
Nachdem Sie den Schlüssel gesichert haben, schließen Sie das Popup. Der neue API-Schlüssel erscheint in der Tabelle „API-Schlüssel“.
Vorhandene API-Schlüssel verwalten
Einen API-Schlüssel bearbeiten
Suchen Sie in der Tabelle „API-Schlüssel“ den Schlüssel, den Sie ändern möchten
Klicken Sie auf die Bearbeiten (Stift)-Symbol neben dem Schlüsselnamen
Aktualisieren Sie die Einstellungen (Name, Beschreibung, Ablauf, IP-Listen)
Klicken Sie Senden um die Änderungen zu speichern
Einen API-Schlüssel löschen
Suchen Sie in der Tabelle „API-Schlüssel“ den Schlüssel, den Sie entfernen möchten
Klicken Sie auf die Löschen (Papierkorb)-Symbol neben dem Schlüsselnamen
Löschen bestätigen
Sofortige Widerrufung
Durch das Löschen eines API-Schlüssels werden alle Zugriffe sofort widerrufen. Alle Anwendungen oder Skripte, die den gelöschten Schlüssel verwenden, schlagen bei der Authentifizierung fehl.
API-Schlüssel verwenden
Authentifizierungsformat
API-Schlüssel werden im HTTP-Authorization-Header als Bearer-Tokens verwendet:
Beispiel-API-Anfrage
Speicherung in Umgebungsvariablen
Laden Sie API-Schlüssel aus Sicherheitsgründen aus Umgebungsvariablen und codieren Sie sie nicht fest ein:
Sicherheitsaspekte
API-Schlüssel wie Passwörter behandeln API-Schlüssel bieten die vollständige Authentifizierung als der zugehörige Benutzer. Schützen Sie sie mit derselben Sorgfalt wie Passwörter.
IP-Beschränkungen verwenden Konfigurieren Sie nach Möglichkeit IP-Zulassungslisten, um einzuschränken, wo der Schlüssel verwendet werden kann. Dadurch wird das Risiko deutlich verringert, falls ein Schlüssel kompromittiert wird.
Ablaufdaten festlegen Vermeiden Sie nach Möglichkeit dauerhafte Schlüssel. Regelmäßiges Ablaufen erzwingt die Schlüsselrotation und begrenzt die Expositionszeiträume.
Schlüsselverwendung überwachen Überprüfen Sie regelmäßig die Felder „Letzte Anmeldung“ und „Letzte Anmelde-IP“, um ungewöhnliche Zugriffsmuster zu erkennen.
Nicht verwendete Schlüssel löschen Entfernen Sie API-Schlüssel, die nicht mehr benötigt werden, um Ihre Angriffsfläche zu minimieren.
Problembehebung
API-Schlüssel-Authentifizierung schlägt fehl
Vergewissern Sie sich, dass der Schlüssel korrekt als Bearer-Token im Authorization-Header enthalten ist. Prüfen Sie auf zusätzliche Leerzeichen oder Abschneidungen.
Zugriff verweigert trotz gültigem Schlüssel
Prüfen Sie die IP-Zulassungs-/Sperrlisten. Ihre Quell-IP ist möglicherweise nicht erlaubt oder steht auf der Sperrliste.
Schlüssel abgelaufen
Prüfen Sie die Spalte „Läuft ab“ in der Tabelle „API-Schlüssel“. Erstellen Sie einen neuen Schlüssel, wenn der alte abgelaufen ist.
Verlorenen Schlüssel nicht abrufen können
API-Schlüssel können nach dem Schließen des ursprünglichen Erstellungs-Popups nicht wiederhergestellt werden. Löschen Sie den verlorenen Schlüssel und erstellen Sie einen neuen.
Verwandte Ressourcen
VergeOS REST API-Dokumentation - Vollständige API-Referenz und Endpunkte
Zuletzt aktualisiert
War das hilfreich?