> 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/run-the-platform/de/systemadministration/api-keys.md). # API-Schlüssel ## Ü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. {% hint style="info" %} **API-Schlüssel vs. Sitzungstokens** Sitzungstokens sind temporäre Anmeldeinformationen, die nach Inaktivität ablaufen. API-Schlüssel sind für langfristigen programmgesteuerten Zugriff konzipiert und bleiben bis zum Ablauf oder zur Löschung gültig. {% endhint %} ## Einen API-Schlüssel erstellen ### Zur API-Schlüssel-Verwaltung navigieren 1. Navigieren Sie im Hauptmenü von VergeOS zu **System > Benutzer** 2. Wählen Sie das Benutzerkonto aus, dem der API-Schlüssel gehören soll 3. 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 1. Klicken Sie **+ Neuer API-Schlüssel** am unteren Rand der Tabelle „API-Schlüssel“ 2. 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. 1. Klicken Sie auf die **+ (Plus)** Symbol zum Hinzufügen eines Eintrags 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-Sperrliste** 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 **+ (Plus)** Symbol zum Hinzufügen eines Eintrags 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 Sperrliste** Wenn beide Listen konfiguriert sind, hat die IP-Zulassungsliste Vorrang. Wenn eine Adresse in beiden Listen vorkommt, bestimmt die Zulassungsliste den Zugriff. {% endhint %} ### API-Schlüssel speichern und abrufen 1. Überprüfen Sie alle Einstellungen auf Genauigkeit 2. 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 {% hint style="danger" %} **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. {% endhint %} 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 1. Suchen Sie in der Tabelle „API-Schlüssel“ 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 **Senden** um die Änderungen zu speichern {% hint style="info" %} **Schlüsselzeichenfolge kann nicht geändert werden** Durch das Bearbeiten eines API-Schlüssels werden nur 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 Tabelle „API-Schlüssel“ 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" %} **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. {% endhint %} ## API-Schlüssel verwenden ### Authentifizierungsformat API-Schlüssel werden im HTTP-Authorization-Header als Bearer-Tokens 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" ``` ### Speicherung in Umgebungsvariablen Laden Sie API-Schlüssel aus Sicherheitsgründen aus Umgebungsvariablen und codieren Sie sie nicht fest ein: ```bash # Umgebungsvariable setzen 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 **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](/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/run-the-platform/de/systemadministration/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.