API-Schlüssel
Wie man API-Schlüssel für den programmatischen Zugriff auf die VergeOS REST-API erstellt, verwaltet und verwendet, einschließlich Authentifizierung, IP-Zugriffskontrollen, Ablauf-Einstellungen und bewährter Sicherheitspraktiken.
Übersicht
API-Schlüssel bieten Authentifizierung für den programmatischen 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 für die REST-API für Automatisierung und Integration
Zugriff auf den mit OpenAI kompatiblen KI-Router
Integration von Drittanbieter-Tools (Überwachung, Orchestrierung, IaC-Tools)
Authentifizierung für CI/CD-Pipelines
API-Schlüssel-Authentifizierung verstehen
API-Schlüssel funktionieren in VergeOS als Bearer-Token im HTTP-Authorization-Header. Im Gegensatz zu Sitzungstokens, die während der UI-Anmeldung generiert 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 des zugehörigen Benutzerkontos. Ein API-Schlüssel, der für einen Tenant-Admin-Benutzer erstellt wurde, verfügt über Tenant-Admin-Rechte, während ein Schlüssel für einen System-Admin systemweiten Zugriff hat.
Einen API-Schlüssel erstellen
Zu API-Schlüssel-Verwaltung navigieren
Im Hauptmenü von VergeOS navigieren Sie zu System > Benutzer
Wählen Sie das Benutzerkonto aus, das Eigentümer des API-Schlüssels sein wird
Klicken Sie im Benutzer-Dashboard auf das API-Schlüssel Widget, um vorhandene Schlüssel anzuzeigen
Der Abschnitt API-Schlüssel zeigt eine Tabelle mit:
Namen: Beschreibende Kennung für jeden Schlüssel
Zuletzt angemeldet: Zeitstempel der letzten Authentifizierung
Letzte angemeldete 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 auf + Neuer API-Schlüssel am unteren Rand der API-Schlüssel-Tabelle
Das Formular öffnet sich mit zwei Bereichen: API-Schlüssel (links) und Zugriff (rechts)
API-Schlüssel-Einstellungen konfigurieren
Namen (Erforderlich) Geben Sie eine beschreibende Kennung 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 aus, wie die Gültigkeitsdauer des Schlüssels verwaltet wird:
Datum festlegen: Ein bestimmtes Ablaufdatum festlegen (aus Sicherheitsgründen empfohlen)
Nie ablaufen: Einen dauerhaften Schlüssel erstellen (mit Vorsicht verwenden)
Läuft ab (Wenn „Datum festlegen“ ausgewählt ist) Verwenden Sie den Datum-/Uhrzeitwähler, um festzulegen, wann der Schlüssel ablaufen soll. Übliche Ablauffristen 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 + (Pluszeichen) Symbol, um einen Eintrag hinzuzufügen
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-Ablehnungsliste Blockieren Sie bestimmte IP-Adressen oder Bereiche für die Verwendung dieses Schlüssels, während alle anderen zugelassen werden.
Klicken Sie auf die + (Pluszeichen) Symbol, um einen Eintrag hinzuzufügen
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 auf Absenden um den API-Schlüssel zu erzeugen
Ein Popup zeigt den generierten API-Schlüssel mit zwei Optionen an:
Kopieren: Klicken Sie hier, um die vollständige Schlüsselzeichenfolge in Ihre Zwischenablage zu kopieren
Speichern: Klicken Sie hier, um den Schlüssel als eine
.PAK(Protected API Key)-Datei
Einmalige Anzeige
Der vollständige API-Schlüssel wird nur beim Erstellen 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 API-Schlüssel-Tabelle.
Vorhandene API-Schlüssel verwalten
Einen API-Schlüssel bearbeiten
Suchen Sie in der API-Schlüssel-Tabelle 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 auf Absenden um Änderungen zu speichern
Einen API-Schlüssel löschen
Suchen Sie in der API-Schlüssel-Tabelle den Schlüssel, den Sie entfernen möchten
Klicken Sie auf die Löschen (Papierkorb)-Symbol neben dem Schlüsselnamen
Löschen bestätigen
Sofortiger Widerruf
Das Löschen eines API-Schlüssels widerruft sofort alle Zugriffe. Alle Anwendungen oder Skripte, die den gelöschten Schlüssel verwenden, werden bei der Authentifizierung fehlschlagen.
API-Schlüssel verwenden
Authentifizierungsformat
API-Schlüssel werden im HTTP-Authorization-Header als Bearer-Token verwendet:
Beispiel-API-Anfrage
Speichern von Umgebungsvariablen
Laden Sie API-Schlüssel aus Sicherheitsgründen aus Umgebungsvariablen und nicht durch festes Eincodieren:
Sicherheitsaspekte
Behandeln Sie API-Schlüssel wie Passwörter 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. Dies reduziert das Risiko erheblich, falls ein Schlüssel kompromittiert wird.
Ablaufdaten festlegen Vermeiden Sie nach Möglichkeit dauerhafte Schlüssel. Regelmäßiger Ablauf erzwingt Schlüsselrotation und begrenzt die Expositionsfenster.
Schlüsselverwendung überwachen Überprüfen Sie regelmäßig die Felder „Zuletzt angemeldet“ und „Letzte angemeldete IP“, um unerwartete 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.
Fehlerbehebung
API-Schlüssel-Authentifizierung schlägt fehl
Stellen Sie sicher, dass der Schlüssel korrekt als Bearer-Token im Authorization-Header enthalten ist. Achten Sie auf zusätzliche Leerzeichen oder Abschneidungen.
Zugriff mit gültigem Schlüssel verweigert
Überprüfen Sie die IP-Zulassungs-/Ablehnungslisten. Ihre Quell-IP ist möglicherweise nicht zulässig oder befindet sich auf der Ablehnungsliste.
Schlüssel abgelaufen
Überprüfen Sie die Spalte „Abläuft“ in der API-Schlüssel-Tabelle. Erstellen Sie einen neuen Schlüssel, wenn der alte abgelaufen ist.
Verlorenen Schlüssel kann nicht abgerufen werden
API-Schlüssel können nach dem Schließen des ersten 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?