API Keys

Mit einem persönlichen API-Schlüssel nutzen Ihre eigenen Skripte und Programme AITEZA in Ihrem Namen, ohne Ihr Passwort. Behandeln Sie API-Schlüssel wie Passwörter: Wer einen Schlüssel hat, kann im Rahmen des Schlüssels in Ihrem Namen handeln.

Es gibt zwei Arten von Schlüsseln:

Wer API-Schlüssel erstellen kann#

• Sie benötigen die Rolle API-Schlüssel. Organisations-Admins vergeben sie auf der Seite Personen (siehe Rollen). Wie jede Rolle gilt sie in allen Organisationen, zu denen Sie gehören. Jeder Schlüssel funktioniert dagegen nur in einer Organisation.
• Mit der Rolle zeigen die Einstellungen im Bereich Persönlich die Seite API-Schlüssel, und auf der Seite Mein Konto steht unter Sie können „Persönliche API-Schlüssel erstellen“. Erscheint die Seite nicht, nachdem Sie die Rolle erhalten haben, melden Sie sich ab und wieder an.
• Steht auf der Seite „API-Schlüssel sind nicht eingeschaltet“, bietet Ihre Installation keine persönlichen API-Schlüssel an. Wenden Sie sich an die Betreiber Ihrer Installation.

Die beiden Schlüsseltypen#

AITEZA-API#

Ein AITEZA-Schlüssel ruft die REST-API von AITEZA als Sie auf, und zwar in der Organisation, in der Sie beim Erstellen gearbeitet haben. Er kann nie mehr, als Sie selbst dürfen, und handelt wie ein einfaches Mitglied dieser Organisation:

• Keine Admin-Rollen. Ihre Admin-Rollen (Organisations-Admin, Datenraum-Admin, Plattform-Administrator) gelten für den Schlüssel nicht. Er erreicht nur die Datenräume, in denen Sie Besitzer, Bearbeiter oder Betrachter sind, direkt oder über eine Gruppe, nicht alle Datenräume der Organisation.
• Nur diese Organisation. Der Schlüssel sieht Ihre anderen Organisationen nicht. So listet GET /api/identity/me/tenants nur die Organisation des Schlüssels auf.
• Alle Ihre Chats und Dateien. Ihre eigenen Chats und Ihre eigenen Dateien, also die von Ihnen hochgeladenen und die von AITEZA für Sie erstellten, sind in AITEZA keiner Organisation zugeordnet. Der Schlüssel kann deshalb alle davon lesen, auch die aus Ihren anderen Organisationen. Ein Schlüssel mit Lesen und Schreiben kann sie außerdem ändern und löschen.

Ändern sich Ihre Zugriffe, ändert sich auch, was der Schlüssel erreicht.

Beim Erstellen wählen Sie den Zugriff des Schlüssels:

Was ein Schlüssel mit Lesen darf, hängt von der HTTP-Methode der Anfrage ab. Alles, was etwas anlegt, ändert oder löscht, auch das Senden einer Chatnachricht, erfordert Lesen und Schreiben. Das gilt auch für manche Funktionen, die nur Daten abrufen, ihre Anfrage aber mit POST senden, zum Beispiel eine Suche in Datenräumen.

Anfragen an KI-Modelle, die Sie mit einem AITEZA-Schlüssel stellen, etwa Chatnachrichten, zählen zu Ihrer Nutzung, genau wie Ihre Anfragen im Browser.

LiteLLM, OpenAI-kompatibel#

Ein LiteLLM-Schlüssel gibt OpenAI-kompatiblen Programmen über https://<Ihr AITEZA-Host>/v1 direkten Zugriff auf die KI-Modelle. Viele Werkzeuge und Bibliotheken, die mit der OpenAI-API arbeiten, funktionieren damit: Sie tragen die Basis-URL und den Schlüssel ein.

• Nur Ihre Modelle. Der Schlüssel kann die Modelle nutzen, die Sie in der Organisation nutzen dürfen, einschließlich der Auswahl Ihrer Gruppen (siehe Welche Modelle eine Person nutzen kann). Ändert sich das, folgt der Schlüssel. Verwenden Sie die Modellnamen, die /v1/models auflistet; sie können von den Namen in der Modellauswahl von AITEZA abweichen.
• Nur Modellaufrufe. Der Schlüssel kann die Modelle aufrufen und auflisten, aber keine anderen Funktionen wie Dateien, Batches oder Assistenten nutzen (siehe Modelle mit einem LiteLLM-Schlüssel aufrufen).
• Monatslimit. Die Admins Ihrer Organisation legen fest, wie viel jede Person pro Monat mit LiteLLM-Schlüsseln verbrauchen darf. Das Limit gilt für Sie, nicht für jeden Schlüssel: Es umfasst alle Ihre LiteLLM-Schlüssel in der Organisation zusammen, auch Schlüssel, die in diesem Monat widerrufen wurden oder abgelaufen sind. Die Seite API-Schlüssel zeigt Ihr Limit und den Verbrauch Ihrer Schlüssel in diesem Monat (siehe Die Seite API-Schlüssel). Haben Ihre Schlüssel das Limit aufgebraucht, werden ihre Anfragen abgelehnt, bis das Limit zu Beginn des nächsten Monats neu beginnt. Sie können weiterhin LiteLLM-Schlüssel erstellen, sie teilen sich aber dasselbe Limit.
• Kosten. Anfragen mit Ihren LiteLLM-Schlüsseln erscheinen auf Ihrer Seite Meine Nutzung und auf der Seite Nutzung der Organisation unter Ihrem Namen.
• Verfügbarkeit. Sie können diesen Typ nur wählen, wenn Ihre Installation LiteLLM-Schlüssel anbietet und die Admins Ihrer Organisation ein Monatslimit festgelegt haben. Andernfalls ist die Option deaktiviert und nennt den Grund: „Auf dieser Installation nicht verfügbar“ oder „Ihre Organisation hat noch kein Limit festgelegt“. Außerdem müssen Sie in der Organisation mindestens ein Modell nutzen dürfen.

AITEZA-Schlüssel funktionieren nicht unter /v1, und LiteLLM-Schlüssel funktionieren nicht mit der REST-API von AITEZA.

Die Seite API-Schlüssel#

Öffnen Sie das Profilmenü, wählen Sie Einstellungen und dann im Bereich Persönlich die Seite API-Schlüssel. Die Seite zeigt Ihre Schlüssel in der Organisation, in der Sie gerade arbeiten (siehe In mehreren Organisationen arbeiten):

• Aktiv mit der Anzahl der Schlüssel, zum Beispiel „Aktiv (2)“: die Schlüssel, die sich verwenden lassen.
• Abgelaufen oder widerrufen: Schlüssel, die nicht mehr gelten. Sie bleiben nach dem Ende 30 Tage lang sichtbar.

Bietet Ihre Organisation LiteLLM-Schlüssel an, zeigt die Seite außerdem Ihr Monatslimit dafür und was alle Ihre LiteLLM-Schlüssel in diesem Monat zusammen verbraucht haben, zum Beispiel „Monatslimit für Ihre LiteLLM-Schlüssel: 25,00 € · 3,10 € in diesem Monat verbraucht“.

Zu jedem Schlüssel sehen Sie:

• seinen Namen,
• den Typ (AITEZA-API oder LiteLLM) und den Anfang des Schlüssels, zum Beispiel azk_AbC1dEf2… oder sk-azp-AbC1dEf2…, damit Sie Schlüssel unterscheiden können,
• bei AITEZA-Schlüsseln den Zugriff (Lesen oder Lesen und Schreiben), bei LiteLLM-Schlüsseln den Verbrauch dieses Schlüssels in diesem Monat, zum Beispiel „3,10 € verbraucht“,
• wann er erstellt wurde, wann er abläuft („Läuft am … ab“) oder endete („Abgelaufen am …“, „Widerrufen am …“) und wann er zuletzt verwendet wurde („Zuletzt verwendet am …“ oder „Noch nie verwendet“).

Schlüssel erstellen#

Der Dialog beginnt mit AITEZA-API, Lesen und 90 Tage. Wählen Sie die kürzeste passende Gültigkeit; 30 Tage ist die sicherste.

• Der Name darf bis zu 100 Zeichen lang sein und muss sich von den Namen Ihrer anderen aktiven Schlüssel unterscheiden.
• Sie können bis zu 10 aktive Schlüssel gleichzeitig haben, über alle Ihre Organisationen gezählt, sofern Ihre Installation keine andere Anzahl festlegt.
• Ein Schlüssel lässt sich nicht verlängern. Erstellen Sie vor dem Ablauf einen neuen Schlüssel, stellen Sie Ihr Programm darauf um und widerrufen Sie den alten.
• Um einen Schlüssel in einer anderen Organisation zu nutzen, wechseln Sie zuerst in diese Organisation und erstellen Sie den Schlüssel dort.

Kann AITEZA den Schlüssel nicht erstellen, nennt der Dialog den Grund:

Der Schlüssel wird nur einmal angezeigt#

Solange der Schlüssel angezeigt wird, schließt ein Klick neben den Dialog oder die Escape-Taste ihn nicht, damit Sie den Schlüssel nicht versehentlich verlieren. Schließen Sie den Dialog mit Fertig, sobald Sie den Schlüssel gespeichert haben.

Unter dem Schlüssel zeigt So verwenden Sie den Schlüssel einen ersten Aufruf zum Ausprobieren, mit der richtigen Adresse Ihrer Installation. Beispiel kopieren kopiert ihn. Bei einem LiteLLM-Schlüssel zeigt der Dialog außerdem die Basis-URL für OpenAI-kompatible Programme.

Schlüssel sicher aufbewahren#

• Bewahren Sie den Schlüssel in einem Passwortmanager oder im Geheimnisspeicher des Systems auf, auf dem Ihr Programm läuft.
• Übergeben Sie ihn Ihrem Programm in einer Umgebungsvariable, zum Beispiel AITEZA_API_KEY oder OPENAI_API_KEY, nicht als Teil des Programms.
• Schreiben Sie einen Schlüssel nie in Quellcode, in Konfigurationsdateien unter Versionsverwaltung, in Chatnachrichten, E-Mails, Tickets oder Prompts. Geben Sie ihn nicht weiter: Wer einen Schlüssel braucht, erstellt einen eigenen.
• Verwenden Sie einen Schlüssel pro Programm oder Zweck, damit Sie einen widerrufen können, ohne die anderen zu beeinträchtigen.
• Bedenken Sie, dass ein AITEZA-Schlüssel alle Ihre eigenen Chats und Dateien erreicht, auch die aus Ihren anderen Organisationen (siehe AITEZA-API). Wer einen Schlüssel mit Lesen und Schreiben hat, kann sie auch ändern und löschen.
• Wählen Sie Lesen und die kürzeste passende Gültigkeit.
• Könnte ein Schlüssel anderen bekannt geworden sein, widerrufen Sie ihn sofort.
• Das Zurücksetzen Ihres Passworts widerruft Ihre Schlüssel nicht. Könnte Ihr Konto kompromittiert sein, widerrufen Sie Ihre Schlüssel oder bitten Sie einen Organisations-Admin, für Sie Überall abmelden zu wählen; das widerruft auch alle Ihre Schlüssel.

Schlüssel verwenden#

Die Beispiele verwenden aiteza.example.com. Ersetzen Sie das durch die Adresse Ihres AITEZA; der Dialog nach dem Erstellen eines Schlüssels zeigt die richtige Adresse. Die Beispiele erwarten den Schlüssel in einer Umgebungsvariable. Damit der Schlüssel nicht im Verlauf Ihrer Shell landet, setzen Sie die Variable zum Beispiel so:

read -rs AITEZA_API_KEY && export AITEZA_API_KEY

Fügen Sie dann den Schlüssel ein und drücken Sie die Eingabetaste. Der Schlüssel erscheint dabei nicht auf dem Bildschirm.

Die AITEZA-API aufrufen#

Senden Sie den Schlüssel als Bearer-Token im Header Authorization. Dieser Aufruf listet die Modelle auf, die Sie nutzen dürfen:

curl https://aiteza.example.com/api/models \
  -H "Authorization: Bearer $AITEZA_API_KEY"

Sie können den Schlüssel auch im Header X-API-Key senden:

curl https://aiteza.example.com/api/models \
  -H "X-API-Key: $AITEZA_API_KEY"

Um die Endpunkte im Browser auszuprobieren, öffnen Sie die API-Referenz unter https://<Ihr AITEZA-Host>/doc/swagger-ui.html, wählen Authorize und geben den Schlüssel unter api_key ein. Endpunkte, die Schlüssel nicht nutzen dürfen, zeigen dort nur die Anmeldung über Keycloak.

• Senden Sie pro Anfrage genau einen Schlüssel und kein weiteres Anmelde-Token.
• Sie müssen keine Organisation wählen: Der Schlüssel gilt immer in seiner eigenen. Sendet Ihr Programm trotzdem den Header X-Tenant-Id, muss er die Organisation des Schlüssels nennen.
• Jeder Schlüssel darf höchstens 60 Anfragen pro Minute stellen, sofern Ihre Installation keine andere Anzahl festlegt. Weitere Anfragen werden mit 429 abgelehnt (siehe Fehlermeldungen).
• Zusätzlich kann Ihre Installation eine großzügige Grenze pro Person festlegen. Sie gilt für alle Ihre Anfragen zusammen, mit allen Schlüsseln und angemeldet in AITEZA, und begrenzt die Anfragen pro Minute und die Anfragen, die gleichzeitig laufen. Ist sie eingeschaltet, nennt jede Antwort im Header RateLimit die noch freien Anfragen und die Sekunden, bis wieder alle frei sind; RateLimit-Policy nennt die Grenze selbst.
• Was Sie mit dem Schlüssel tun, wird im Audit-Log unter Ihrem Namen festgehalten. Die Details des Ereignisses nennen den Schlüssel (apiKey und apiKeyName). Anfragen, die AITEZA wegen der Grenzen des Schlüssels ablehnt, zum Beispiel eine Verwaltungsfunktion, eine andere Organisation oder eine Änderung mit einem Schlüssel mit Lesen, werden als „Zugriff verweigert“ festgehalten. So fällt der Missbrauch eines verlorenen Schlüssels auf.

Modelle mit einem LiteLLM-Schlüssel aufrufen#

Verwenden Sie https://<Ihr AITEZA-Host>/v1 als Basis-URL. Viele OpenAI-kompatible Programme lesen den Schlüssel selbst aus der Umgebungsvariable OPENAI_API_KEY. Dieser Aufruf listet die Modelle auf, die der Schlüssel nutzen darf:

curl https://aiteza.example.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Eine Chat-Anfrage, mit einem der aufgelisteten Modellnamen statt MODEL_NAME:

curl https://aiteza.example.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "messages": [{"role": "user", "content": "Hallo"}]}'

Dasselbe mit der OpenAI-Bibliothek für Python (pip install openai):

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://aiteza.example.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[{"role": "user", "content": "Hallo"}],
)
print(response.choices[0].message.content)

• Senden Sie den Schlüssel genau einmal, als Authorization: Bearer sk-azp-…. Die OpenAI-Client-Bibliotheken tun das von selbst. Andere Schreibweisen werden mit 401 abgelehnt, zum Beispiel der Schlüssel in der Adresse, der Schlüssel doppelt, Basic statt Bearer oder ein anderer Header mit zusätzlichem Text.
• Der Schlüssel kann nur Modell-Endpunkte aufrufen: Chat Completions, Completions, Responses, Embeddings, die Modellliste, Moderations, Rerank, Audio (Transkription, Übersetzung, Sprachausgabe) und Bilder (Erzeugen, Bearbeiten, Variationen). Andere Endpunkte, zum Beispiel Dateien, Batches, Vector Stores, Assistenten, Fine-Tuning oder MCP, werden mit 403 abgelehnt.
• Der Inhalt einer Anfrage muss, außer bei Datei-Uploads, ein einzelnes JSON-Objekt ohne doppelte Felder sein, und das Modell muss zu Ihren Modellen gehören. Das automatische Ausweichen von LiteLLM auf andere Modelle ist für diese Schlüssel abgeschaltet.
• Jeder LiteLLM-Schlüssel kann höchstens 4 Anfragen gleichzeitig ausführen, und alle Ihre LiteLLM-Schlüssel in der Organisation können zusammen höchstens 60 Anfragen pro Minute stellen, sofern Ihre Installation keine anderen Werte festlegt.

Was Schlüssel nicht können#

Für AITEZA-Schlüssel gelten unabhängig vom Zugriff diese Grenzen:

• Keine Verwaltung. Ein Schlüssel kann die Verwaltung der Organisation (/api/admin/…), die Plattformverwaltung (/api/platform/…) und einige weitere Verwaltungsfunktionen nicht nutzen. Ihre Admin-Rollen (Organisations-Admin, Datenraum-Admin, Plattform-Administrator) und Ihre Verwaltungsrechte gelten für Anfragen mit einem Schlüssel nicht.
• Keine Schlüsselverwaltung. Ein Schlüssel kann keine API-Schlüssel erstellen, auflisten oder widerrufen. Ihre Schlüssel verwalten Sie nur auf der Seite API-Schlüssel.
• Keine Workflows. Workflows lassen sich mit einem Schlüssel nicht starten, weder direkt noch über eine Chatnachricht. Führen Sie Workflows angemeldet in AITEZA aus.
• Lese-Schlüssel schreiben nicht. Ein Schlüssel mit dem Zugriff Lesen nimmt nur GET, HEAD und OPTIONS an. Jede andere Methode wird abgelehnt, und der Schlüssel kann nichts anlegen, auch keinen Chat.
• Eine Organisation. Ein Schlüssel funktioniert nur in der Organisation, in der er erstellt wurde. Nur Ihre eigenen Chats und Dateien erreicht er über Organisationen hinweg (siehe AITEZA-API).
• Höchstens 60 Anfragen pro Minute. Weitere Anfragen werden abgelehnt, bis die im Header Retry-After genannte Zeit vergangen ist. Ihre Installation kann eine andere Anzahl festlegen.

LiteLLM-Schlüssel können nur Modell-Endpunkte aufrufen, und nur mit Ihren Modellen (siehe Modelle mit einem LiteLLM-Schlüssel aufrufen).

Wann ein Schlüssel nicht mehr funktioniert#

• Er läuft am Ende seiner Gültigkeit ab.
• Sie oder ein Organisations-Admin widerrufen ihn.
• Ein Organisations-Admin meldet Sie überall ab, deaktiviert Ihr Konto oder entzieht Ihnen die Rolle API-Schlüssel. Das widerruft alle Ihre Schlüssel, in jeder Organisation. Werden Sie aus einer Organisation entfernt, werden Ihre Schlüssel in dieser Organisation widerrufen.
• Sie verlieren den Zugriff auf andere Weise, zum Beispiel weil Ihr Konto direkt in der Identitätsverwaltung (Keycloak) Ihrer Installation deaktiviert wird, Ihnen dort die Rolle entzogen wird oder Sie dort die Organisation verlassen. Ihre Schlüssel werden dann innerhalb von etwa einer Minute abgelehnt und innerhalb von 15 Minuten widerrufen.
• Die Betreiber Ihrer Installation schalten die API-Schlüssel ab. Schlüssel, die weder widerrufen noch abgelaufen sind, funktionieren wieder, sobald die API-Schlüssel wieder eingeschaltet werden.

Widerrufene Schlüssel bleiben widerrufen: Erhalten Sie Ihren Zugriff zurück, funktionieren alte Schlüssel nicht wieder; erstellen Sie neue. Das Zurücksetzen Ihres Passworts widerruft Ihre Schlüssel nicht.

Schlüssel widerrufen#

Programme, die den Schlüssel verwenden, verlieren sofort den Zugriff. Das lässt sich nicht rückgängig machen. Der Schlüssel wechselt zu Abgelaufen oder widerrufen und bleibt dort 30 Tage lang sichtbar. Ein widerrufener LiteLLM-Schlüssel wird auch in LiteLLM gelöscht.

Auch Organisations-Admins können Ihre Schlüssel widerrufen (siehe Schlüssel anderer Personen widerrufen).

Fehlermeldungen#

Lehnt AITEZA eine Anfrage mit einem AITEZA-Schlüssel ab, antwortet es mit einem HTTP-Status und einem JSON-Text mit Code und kurzer Meldung, zum Beispiel:

Andere Antworten bedeuten dasselbe wie in AITEZA selbst, zum Beispiel 404 für etwas, das es nicht gibt.

Anfragen mit einem LiteLLM-Schlüssel an /v1 werden im Fehlerformat der OpenAI-API beantwortet, mit der Erklärung in error.message:

Haben Ihre LiteLLM-Schlüssel Ihr Monatslimit aufgebraucht, lehnt LiteLLM weitere Anfragen selbst ab, mit dem Status 400 und einer Meldung über das überschrittene Budget, bis das Limit zu Beginn des nächsten Monats neu beginnt. Auch Anfragen über die Grenzen für gleichzeitige Anfragen und Anfragen pro Minute hinaus lehnt LiteLLM ab.