Zum Hauptinhalt springen

API-Keys verwalten

API-Keys ermöglichen es externen Diensten, Anwendungen und der CLYE CLI, sicher mit deiner CLYE-AI-Instanz zu kommunizieren. Sie sind der zentrale Zugangsschlüssel für alle programmatischen Zugriffe.

Was ist ein API-Key?​

Ein API-Key ist ein geheimer Token, der eine Anwendung oder einen Dienst gegenüber CLYE AI authentifiziert. Anders als ein Passwort ist ein API-Key nicht an eine Person, sondern an eine Anwendung oder Integration gebunden.

API-Keys werden benötigt für:

API-Key erstellen​

info

Nur Space-Admins und Nutzer mit entsprechenden Berechtigungen können API-Keys erstellen.

  1. Öffne den gewünschten Space und gehe zu Space-Einstellungen → Integrationen → API-Schlüssel. Dort siehst du bestehende Schlüssel und kannst neue anlegen.
  2. Klicke auf API-Key erstellen.
  3. Gib einen Namen ein (z. B. "Mein CLI-Zugang" oder "LLM-Gateway-Produktion").
  4. Trage bei Bedarf eine Beschreibung ein, damit andere Admins den Einsatzzweck des Keys später schneller verstehen. Beschreibe kurz, wofür der Key gedacht ist, zum Beispiel „CLI für lokale Entwicklung“ oder „Produktiver Zugriff fürs LLM Gateway“.
  5. Wähle optional die Berechtigungen (Scopes) für den Key.
  6. Klicke auf Erstellen.
warnung

Nach dem Erstellen wird der Key nur einmal angezeigt. Kopiere ihn sofort und bewahre ihn sicher auf – zum Beispiel in einem Passwort-Manager oder einer .env-Datei.

Berechtigungen (Scopes)​

Ein API-Key kann auf bestimmte Aktionen eingeschränkt werden. Typische Berechtigungen sind:

ScopeBeschreibung
ChatNachrichten senden und Chats führen
DateienDateien in Workspaces lesen und hochladen
AufgabenAufgaben erstellen, bearbeiten und abschließen
AdminSpace-Einstellungen lesen und ändern
LLM GatewayZugriff auf das LLM Gateway

Du kannst mehrere Berechtigungen pro Key kombinieren. Für jeden Key solltest du nur die Berechtigungen wählen, die die Anwendung wirklich braucht (Prinzip der minimalen Rechte).

Namen und Beschreibungen sinnvoll vergeben​

Verwende für Name und Beschreibung möglichst eindeutige Angaben. So erkennst du später in der Übersicht schneller, welcher Key noch benötigt wird und welcher Zweck dahintersteckt.

Bewährt haben sich kurze Kombinationen aus System, Zweck und Umgebung, zum Beispiel:

  • Name: CLI Produktion Beschreibung: Manueller Zugriff für Admin-Aufgaben im Produktivsystem
  • Name: LLM Gateway Support-Bot Beschreibung: API-Zugang für den extern eingebetteten Support-Assistenten
  • Name: CRM Sync Staging Beschreibung: Test-Key für die Staging-Integration mit dem CRM

Vermeide generische Bezeichnungen wie Test, Neu oder API Key, weil sich solche Einträge später kaum auseinanderhalten lassen.

API-Key verwenden​

In der CLYE CLI​

export AI_HUB_URL="https://clye.ai"
export AI_HUB_API_KEY="dein-api-key-here"

clye connect

Im HTTP-Header​

Authorization: Bearer dein-api-key-here
Content-Type: application/json

Für MCP-Hub-Aufrufe​

Wenn du einen Space-Admin-API-Key für den Space-MCP-Hub nutzt, gelten Feature-Flags des zugehörigen Space jetzt konsistent auch für diesen API-Zugriff. Entscheidend ist dabei die Freigabe des Key-Erstellers in /admin/testing.

Praktisch heißt das: Ist das benötigte Feature dort für den Key-Ersteller aktiviert, funktionieren Aufrufe wie initialize oder tools/list auch über den API-Key. Ohne passende Freigabe bleibt der Zugriff weiterhin gesperrt.

API-Key widerrufen​

Wenn ein Key kompromittiert ist oder nicht mehr benötigt wird, solltest du ihn sofort widerrufen:

  1. Öffne den gewünschten Space und gehe zu Space-Einstellungen → Integrationen → API-Schlüssel. Dort siehst du bestehende Schlüssel und kannst neue anlegen.
  2. Finde den entsprechenden Key in der Liste.
  3. Klicke auf Widerrufen (oder das Papierkorb-Symbol).
  4. Bestätige den Widerruf.
warnung

Nach dem Widerruf können alle Dienste, die diesen Key verwenden, nicht mehr auf CLYE AI zugreifen. Stelle sicher, dass du den Key in allen Anwendungen ersetzt hast, bevor du ihn widerrufst.

Best Practices​

  • Keys rotieren: Erstelle regelmäßig neue Keys und widerrufe alte.
  • Minimale Rechte: Gib jedem Key nur die Berechtigungen, die er wirklich braucht.
  • Sicher ablegen: Speichere Keys in einem Passwort-Manager oder einer verschlüsselten .env-Datei.
  • Nicht im Code: Hinterlege Keys nie direkt im Quellcode, besonders nicht in öffentlichen Repositories.
  • Nicht in URLs: Übergebe API-Keys nach Möglichkeit immer im Header statt als URL-Parameter.
  • Namen vergeben: Verwende aussagekräftige Namen, damit du später weißt, wofür ein Key erstellt wurde.
  • Überwachung: Prüfe regelmäßig die Liste der aktiven Keys und widerrufe ungenutzte.

Limits​

  • Die maximale Anzahl aktiver API-Keys pro Space ist begrenzt (siehe Space-Einstellungen).
  • API-Keys haben ein Ablaufdatum. Du wirst rechtzeitig benachrichtigt, wenn ein Key bald abläuft.
  • Bei wiederholter Nutzung eines widerrufenen Keys erhältst du einen HTTP-401-Fehler.
  • Wird der zugehörige Space gelöscht, verlieren seine API-Keys sofort ihre Gültigkeit. Bereits gecachte Schlüssel oder spätere Verbindungsversuche werden verworfen.

Kurz gesagt​

API-Keys sind der sichere Zugangsschlüssel für CLI, LLM Gateway und externe Integrationen. Erstelle Keys mit minimalen Rechten, bewahre sie sicher auf und widerrufe nicht mehr benötigte Keys umgehend.

Inhalt