API: Authentifizierung

Wie Sie Kasimir-API-Schlüssel erstellen und Requests an die OpenAI-kompatible REST-API per Bearer-Token authentifizieren.

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, können Sie das offizielle OpenAI-SDK unverändert verwenden – Sie setzen 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) 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.

Öffnen Sie /administration/access.
Vergeben Sie einen sprechenden Namen (z. B. ci-pipeline oder crm-integration).
Erstellen Sie den Schlüssel.
Kopieren Sie 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 Klartext-Schlüssel wird genau einmal bei der Erstellung zurückgegeben. Kasimir speichert nur einen SHA-256-Hash des Geheimnisses – es gibt keine Möglichkeit, einen verlorenen Schlüssel erneut anzuzeigen. Geht er verloren, widerrufen Sie ihn und erstellen einen neuen.

Schlüsselformat

Jeder Schlüssel hat das Format kasi_<32 Zeichen>. Die 32 Zeichen stammen aus einem 32-stelligen Base32-ähnlichen Alphabet (a–z, 2–7), was 160 Bit Entropie ergibt. Das Präfix kasi_ macht Schlüssel in Logs erkennbar. In der Verwaltungsoberfläche sehen Sie nach dem Erstellen nur noch das Präfix (die ersten 9 Zeichen, z. B. kasi_abx7) zur Identifikation.

Scopes

Beim Erstellen können Scopes angegeben werden; ohne Angabe erhält der Schlüssel die Standard-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

Senden Sie 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": "chat1",
    "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="chat1",
    messages=[{"role": "user", "content": "Sag Hallo auf Deutsch."}],
)
print(resp.choices[0].message.content)

💡

Setzen Sie den Schlüssel über die Umgebungsvariable OPENAI_API_KEY und OPENAI_BASE_URL, dann konfiguriert sich das SDK ohne Code-Änderung. Schreiben Sie 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`) oder nicht-EU-Modell ohne Freigabe
`404`	`not_found_error`	Modell unbekannt/deaktiviert oder Assistent nicht gefunden
`400`	`invalid_request_error`	Ungültiger Request-Body
`5xx`	`api_error`	Interner Fehler oder Upstream-Problem

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

In /administration/access sehen owner/admin alle Schlüssel der Organisation mit Name, Präfix, Scopes, Erstellungsdatum und last_used_at (wird bei jedem authentifizierten Request best-effort aktualisiert). Ein Widerruf setzt revoked_at – widerrufene Schlüssel werden ab sofort mit 401 API key revoked abgelehnt. Ein Widerruf ist endgültig; es gibt keine Reaktivierung.

💡

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

Sicherheitshinweise

Behandeln Sie API-Schlüssel wie Passwörter: niemals committen, niemals an Clients/Browser ausliefern, niemals in Logs schreiben.
Schlüssel haben keinen Ablauf – rotieren Sie sie regelmäßig durch Widerruf + Neuerstellung.
Die gesamte Nutzung über die API zählt zusammen mit der In-App-Chat-Nutzung auf das Monatsbudget der Organisation.
Modell-Governance gilt identisch zur App: deaktivierte Modelle und nicht-EU-Modelle (ohne Opt-in der Organisation) sind auch über die API gesperrt.

ZurückAPI-Überblick WeiterAPI: Chat Completions