API: Authentifizierung

Wie du Kasimir-API-Schlüssel erstellst und Requests an die OpenAI-kompatible REST-API per Bearer-Token authentifizierst.

Die öffentliche Kasimir-API ist OpenAI-kompatibel und unter der Basis-URL https://kasimir.ai/api/v1 erreichbar. Jeder Request wird über einen firmengebundenen API-Schlüssel im Authorization-Header authentifiziert – es gibt keine Session, keine Cookies und kein OAuth. Ein Schlüssel repräsentiert immer genau eine Organisation (Mandant), und sämtliche Nutzung (Tokens, Kosten) wird auf das Monatsbudget dieser Organisation verrechnet. Weil die Wire-Formate denen von OpenAI entsprechen, kannst du das offizielle OpenAI-SDK unverändert verwenden – du setzt lediglich base_url und api_key.

Überblick

Eigenschaft	Wert
Basis-URL	`https://kasimir.ai/api/v1`
Auth-Schema	`Authorization: Bearer <api-key>`
Schlüsselformat	`kasi_` + 32 Zeichen (z. B. `kasi_abx7k2m9...`)
Geltungsbereich	pro Organisation (Mandant)
Kompatibilität	OpenAI Chat Completions, Embeddings, Models

Der API-Schlüssel ist mandantengebunden, nicht benutzergebunden. Jeder Request läuft im Kontext der Organisation, für die der Schlüssel erstellt wurde – mit deren freigeschalteten Modellen, deren Modell-Governance (EU-Gate, deaktivierte Modelle, Tarif) und deren Monatsbudget.

API-Schlüssel erstellen

API-Schlüssel werden ausschließlich in der Weboberfläche unter Administration → Zugriff (/administration/access) verwaltet. Nur Mitglieder mit der Rolle owner oder admin dürfen Schlüssel anlegen, auflisten oder widerrufen.

Öffne /administration/access und klicke bei API-Keys auf Neuer Key.
Vergib einen sprechenden Namen (z. B. ci-pipeline oder crm-integration).
Klicke auf Erstellen.
Kopiere den vollständigen Schlüssel sofort – er wird nur ein einziges Mal im Klartext angezeigt.

API-Schlüssel werden unter Administration → Zugriff erstellt; der Klartext erscheint nur einmal.

Der vollständige Schlüssel wird nur einmal angezeigt – direkt nach dem Erstellen. Kasimir kann ihn danach nicht mehr anzeigen. Geht er verloren, widerrufe ihn und erstelle einen neuen.

Schlüsselformat

Ein Schlüssel beginnt mit kasi_. In der Liste siehst du danach nur noch den Anfang (z. B. kasi_ab3f…), damit du ihn wiedererkennst.

Scopes

Beim Erstellen fragt Kasimir nur nach einem Namen; jeder Schlüssel erhält die Scopes chat:read und chat:write.

Scope	Bedeutung	Erforderlich für
`chat:read`	Lesezugriff (Modell-Liste)	–
`chat:write`	Inferenz ausführen	`POST /chat/completions`, `POST /embeddings`, `POST /assistants/{id}/run`

Die Laufzeit-Endpunkte (Chat, Embeddings, Assistant-Run) verlangen alle den Scope chat:write. GET /models verlangt nur einen gültigen Schlüssel (kein spezifischer Scope). In der Praxis benötigt fast jede Integration chat:write.

Authentifizierung im Request

Sende den Schlüssel als Bearer-Token im Authorization-Header. Erwartet wird exakt das Muster Bearer <schlüssel> (Groß-/Kleinschreibung des Wortes „Bearer" wird toleriert).

curl https://kasimir.ai/api/v1/chat/completions \
  -H "Authorization: Bearer kasi_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-31b",
    "messages": [
      { "role": "user", "content": "Sag Hallo auf Deutsch." }
    ]
  }'

Schneller Verbindungstest gegen den models-Endpunkt (benötigt nur einen gültigen Schlüssel):

curl https://kasimir.ai/api/v1/models \
  -H "Authorization: Bearer kasi_DEIN_SCHLUESSEL"

Mit dem OpenAI Python SDK

Da die API OpenAI-kompatibel ist, genügt das Umstellen von base_url und api_key:

from openai import OpenAI

client = OpenAI(
    api_key="kasi_DEIN_SCHLUESSEL",
    base_url="https://kasimir.ai/api/v1",
)

# Verfügbare Modelle auflisten
for m in client.models.list().data:
    print(m.id)

# Chat-Completion
resp = client.chat.completions.create(
    model="gemma-4-31b",
    messages=[{"role": "user", "content": "Sag Hallo auf Deutsch."}],
)
print(resp.choices[0].message.content)

Setze den Schlüssel über die Umgebungsvariablen OPENAI_API_KEY und OPENAI_BASE_URL, dann konfiguriert sich das SDK ohne Code-Änderung. Schreib Schlüssel niemals in den Quellcode oder ins Repository.

Fehlerformat

Authentifizierungs- und sonstige Fehler werden im OpenAI-Fehlerformat zurückgegeben, sodass off-the-shelf-SDKs sie normal verarbeiten:

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": null
  }
}

Auth- und budgetbezogene Statuscodes

Status	`type`	Ursache
`401`	`authentication_error`	Kein Bearer-Token, ungültiger Schlüssel oder widerrufener Schlüssel
`402`	`insufficient_quota`	Monatsbudget der Organisation erreicht
`403`	`permission_error`	Fehlender Scope (z. B. `chat:write`), Modell deaktiviert, Nicht-EU-Modell ohne Freigabe, Modell nicht im Tarif enthalten oder Organisation gesperrt
`404`	`not_found_error`	Modell unbekannt oder Agent nicht gefunden
`429`	`invalid_request_error`	Zu viele Anfragen in kurzer Zeit mit diesem Schlüssel
`400`	`invalid_request_error`	Ungültiger Request-Body
`5xx`	`api_error`	Vorübergehender Fehler bei der Verarbeitung

Konkrete 401-Meldungen je nach Ursache: Missing bearer token, Invalid API key, API key revoked. Ein fehlender Scope liefert 403 mit Missing scope: chat:write.

Beim gestreamten Chat ("stream": true) werden Fehler, die vor Beginn des Streams auftreten (z. B. Auth, Budget), als normaler JSON-Fehler geliefert. Tritt der Fehler erst während des laufenden SSE-Streams auf, kann er nicht mehr in das JSON-Format umgewandelt werden – der Stream bricht dann ab.

Schlüssel verwalten und widerrufen

Unter Administration → Zugriff sehen owner/admin alle Schlüssel der Organisation mit Name, Präfix, Scopes, Erstellungsdatum und letzter Nutzung. Widerrufene Schlüssel werden ab sofort mit 401 API key revoked abgelehnt. Ein Widerruf ist endgültig; es gibt keine Reaktivierung.

Verwende pro Integration/Umgebung einen eigenen benannten Schlüssel (z. B. prod-backend, staging, analytics-job). So kannst du einen kompromittierten oder ausgemusterten Schlüssel gezielt widerrufen, ohne andere Integrationen zu beeinträchtigen. Namen müssen pro Organisation eindeutig sein.

Sicherheitshinweise

Behandle API-Schlüssel wie Passwörter: niemals committen, niemals an Clients/Browser ausliefern, niemals in Logs schreiben.
Schlüssel haben keinen Ablauf – rotiere sie regelmäßig durch Widerruf + Neuerstellung.
Die gesamte Nutzung über die API zählt zusammen mit allen anderen KI-Kosten der Organisation (Chat, Workflows, Bilder und mehr) auf ihr Monatsbudget.
Modell-Governance gilt identisch zur App: deaktivierte Modelle, nicht-EU-Modelle (ohne Opt-in der Organisation) und Modelle, die der Tarif nicht enthält, sind auch über die API gesperrt.

ZurückAPI-Überblick WeiterAPI: Chat Completions