> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/de/gemeinsame-admin-oberflachen/api-keys.md). # API-Schlüssel ## Ü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. {% hint style="info" %} **API-Schlüssel vs. Sitzungstokens** Sitzungstokens sind temporäre Anmeldedaten, die nach Inaktivität ablaufen. API-Schlüssel sind für langfristigen programmatischen Zugriff konzipiert und bleiben bis zum Ablauf oder zur Löschung gültig. {% endhint %} ## Einen API-Schlüssel erstellen ### Zu API-Schlüssel-Verwaltung navigieren 1. Im Hauptmenü von VergeOS navigieren Sie zu **System > Benutzer** 2. Wählen Sie das Benutzerkonto aus, das Eigentümer des API-Schlüssels sein wird 3. 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 1. Klicken Sie auf **+ Neuer API-Schlüssel** am unteren Rand der API-Schlüssel-Tabelle 2. 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. 1. Klicken Sie auf die **+ (Pluszeichen)** Symbol, um einen Eintrag hinzuzufügen 2. Geben Sie eine IP-Adresse ein (z. B., `192.168.1.100`) oder einen CIDR-Bereich (z. B., `192.168.1.0/24`) 3. Aktivieren Sie das Kontrollkästchen, um den Eintrag zu aktivieren 4. 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. 1. Klicken Sie auf die **+ (Pluszeichen)** Symbol, um einen Eintrag hinzuzufügen 2. Geben Sie die zu blockierende IP-Adresse oder den CIDR-Bereich ein 3. Aktivieren Sie das Kontrollkästchen, um den Eintrag zu aktivieren {% hint style="info" %} **Priorität von Zulassungs- gegenüber Ablehnungsliste** Wenn beide Listen konfiguriert sind, hat die IP-Zulassungsliste Vorrang. Wenn eine Adresse in beiden Listen erscheint, bestimmt die Zulassungsliste den Zugriff. {% endhint %} ### API-Schlüssel speichern und abrufen 1. Überprüfen Sie alle Einstellungen auf Genauigkeit 2. 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 {% hint style="danger" %} **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. {% endhint %} 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 1. Suchen Sie in der API-Schlüssel-Tabelle den Schlüssel, den Sie ändern möchten 2. Klicken Sie auf die **Bearbeiten** (Stift)-Symbol neben dem Schlüsselnamen 3. Aktualisieren Sie die Einstellungen (Name, Beschreibung, Ablauf, IP-Listen) 4. Klicken Sie auf **Absenden** um Änderungen zu speichern {% hint style="info" %} **Schlüsselzeichenfolge kann nicht geändert werden** Durch die Bearbeitung eines API-Schlüssels werden nur dessen Metadaten und Zugriffskontrollen aktualisiert. Die eigentliche Schlüsselzeichenfolge kann nicht geändert werden. Um die Schlüsselzeichenfolge zu ändern, müssen Sie einen neuen API-Schlüssel erstellen und den alten löschen. {% endhint %} ### Einen API-Schlüssel löschen 1. Suchen Sie in der API-Schlüssel-Tabelle den Schlüssel, den Sie entfernen möchten 2. Klicken Sie auf die **Löschen** (Papierkorb)-Symbol neben dem Schlüsselnamen 3. Löschen bestätigen {% hint style="warning" %} **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. {% endhint %} ## API-Schlüssel verwenden ### Authentifizierungsformat API-Schlüssel werden im HTTP-Authorization-Header als Bearer-Token verwendet: ``` Authorization: Bearer ``` ### Beispiel-API-Anfrage ```bash curl -X GET "https://your-vergeos-instance/api/v4/system" \ -H "Authorization: Bearer your-api-key-string-here" \ -H "Content-Type: application/json" ``` ### Speichern von Umgebungsvariablen Laden Sie API-Schlüssel aus Sicherheitsgründen aus Umgebungsvariablen und nicht durch festes Eincodieren: ```bash # Umgebungsvariable festlegen export VERGEOS_API_KEY="your-api-key-string" # In der API-Anfrage verwenden curl -X GET "https://your-vergeos-instance/api/v4/system" \ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` ## 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](/knowledge-base/de/automation-api/verge-api-guide.md) - Vollständige API-Referenz und Endpunkte --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/automate-protect-and-extend/de/gemeinsame-admin-oberflachen/api-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.