Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Authentifizierung

Gilt für

Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator

Jede Anfrage an die API muss mit einem gültigen API-Token und einem korrekten X-Realm-Header authentifiziert werden. API-Tokens für Ihre Organisation erstellen Sie im Abschnitt API Token des basebox-Administrationsbereichs.

Note

Die REST-API ist eine optionale Funktion; Ihre basebox-Lizenz muss ihre Nutzung abdecken. Auf basebox Server müssen Sie zusätzlich sicherstellen, dass die Umgebungsvariable AISRV_ENABLE_REST_API auf true gesetzt ist.

Ist das nicht der Fall, wird der Abschnitt API Token im basebox-Adminbereich nicht angezeigt.

X-Realm

Mit dem X-Realm-Header geben Sie den Realm (die Subdomain) der Organisation an, die das API-Token erstellt hat. Je nachdem, ob Sie basebox in der Cloud (z. B. <yourdomain>.basebox.ai) oder auf basebox Server nutzen, unterscheidet sich der Realm:

Cloud

Der Wert für den X-Realm-Header ist die Subdomain Ihrer Organisation. Lautet Ihre basebox.ai-Domain zum Beispiel myorg.basebox.ai, ist der Wert für den X-Realm-Header myorg.

basebox Server

Der Wert für den X-Realm-Header ist in der Regel primary. Der Wert Ihrer basebox-Server-Installation kann abweichen; melden Sie sich in diesem Fall an Ihrer basebox-Instanz an, öffnen Sie das Hauptmenü und klicken Sie auf Über basebox. Der benötigte Name steht in der Zeile Realm.

API-Token

API-Tokens sind base64-kodierte Zeichenketten, die Organisationsadministratoren erstellen können.

API-Tokens erstellen

So erstellen Sie ein neues API-Token:

1. Melden Sie sich bei basebox an und öffnen Sie den Administrationsbereich.
2. Navigieren Sie zum Abschnitt API Token.
3. Klicken Sie auf die Schaltfläche Create Token.
4. Geben Sie einen Namen für Ihr Token ein.
5. Klicken Sie auf die Schaltfläche Create.

Das Token wird auf dem Bildschirm angezeigt. Kopieren Sie es und bewahren Sie es sicher auf, am besten in einem Passwortmanager. Das Token wird nicht erneut angezeigt – speichern Sie es also sicher. Wenn Sie Ihr Token verlieren, müssen Sie ein neues erstellen.

API-Token verwenden

Übergeben Sie das Token im HTTP-Header Authorization Ihrer Anfragen als Bearer-Token:

Authorization: Bearer <token>

Beispiel

Ein einfaches Beispiel mit curl, das die Verwendung von X-Realm-Header und API-Token zeigt:

curl -X POST \
  https://aims.basebox.ai/rest/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'X-Realm: myorg' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "model": "ai.basebox.assistant",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Hello! How are you today?"
      }
    ]
  }'