SilentChat

Authentifizierung

Die SilentChat API unterstützt zwei Authentifizierungsmethoden: JWT-Bearer-Tokens für benutzerbasierte Zugriffe und API-Schlüssel für Server-zu-Server-Integrationen.

JWT-Bearer-Tokens

JWT-Tokens sind die primäre Authentifizierungsmethode für Benutzer, die mit der API interagieren. Sie erhalten Tokens, indem Sie sich über den Endpunkt /v1/auth/login anmelden.

Tokens abrufen

Senden Sie eine POST-Anfrage an den Login-Endpunkt mit Ihren Zugangsdaten:

POST /v1/auth/login HTTP/1.1
Host: api.silentchat.de
Content-Type: application/json


{
  "email": "jane@example.com",
  "password": "your-password"
}

Eine erfolgreiche Antwort gibt ein Access-Token und ein Refresh-Token zurück:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "token_type": "Bearer",
  "expires_in": 900
}

Das Access-Token verwenden

Fügen Sie das Access-Token in den Authorization-Header jeder API-Anfrage ein:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Access-Tokens laufen nach 15 Minuten ab. Wenn ein Token abläuft, antwortet die API mit 401 Unauthorized.

Tokens erneuern

Bevor oder nachdem das Access-Token abläuft, tauschen Sie das Refresh-Token gegen ein neues Access-Token aus:

POST /v1/auth/refresh HTTP/1.1
Host: api.silentchat.de
Content-Type: application/json


{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
}

Refresh-Tokens sind Einmal-Tokens. Jede Erneuerungsanfrage gibt ein neues Refresh-Token zurück und invalidiert das vorherige. Refresh-Tokens laufen nach 30 Tagen ab.

Token-Erneuerungsablauf

  1. Der Client stellt eine API-Anfrage mit dem Access-Token.
  2. Der Server antwortet mit 401 Unauthorized, weil das Token abgelaufen ist.
  3. Der Client sendet das Refresh-Token an POST /v1/auth/refresh.
  4. Der Server gibt ein neues Access-Token und ein neues Refresh-Token zurück.
  5. Der Client wiederholt die ursprüngliche Anfrage mit dem neuen Access-Token.

API-Schlüssel-Authentifizierung

Für Server-zu-Server-Integrationen können Sie sich mit einem API-Schlüssel anstelle von JWT-Tokens authentifizieren. API-Schlüssel haben eine lange Lebensdauer und laufen nicht automatisch ab.

Einen API-Schlüssel erstellen

  1. Gehen Sie im Dashboard zu Einstellungen → API-Schlüssel.
  2. Klicken Sie auf Neuer API-Schlüssel und geben Sie ihm einen aussagekräftigen Namen (z. B. Produktions-Backend).
  3. Wählen Sie die Berechtigungen (Scopes), die der Schlüssel haben soll.
  4. Klicken Sie auf Erstellen und kopieren Sie den Schlüssel sofort — er wird nicht erneut angezeigt.

Den API-Schlüssel verwenden

Übergeben Sie den Schlüssel im X-API-Key-Header:

X-API-Key: sk_live_abc123def456...

Bei Verwendung eines API-Schlüssels müssen Sie auch den X-Tenant-ID-Header angeben, um festzulegen, auf welchen Tenant die Anfrage bezogen ist:

GET /v1/conversations HTTP/1.1
Host: api.silentchat.de
X-API-Key: sk_live_abc123def456...
X-Tenant-ID: tn_abc123
Content-Type: application/json

Sicherheits-Best-Practices

  • Geben Sie Ihren API-Schlüssel oder Ihr Refresh-Token niemals in clientseitigem Code oder öffentlichen Repositories preis.
  • Speichern Sie Geheimnisse in Umgebungsvariablen oder einem Secrets-Manager, niemals im Quellcode.
  • Verwenden Sie beim Erstellen von API-Schlüsseln die minimal erforderlichen Berechtigungen.
  • Rotieren Sie API-Schlüssel regelmäßig und widerrufen Sie solche, die möglicherweise kompromittiert wurden.
  • Verwenden Sie immer HTTPS — senden Sie Tokens niemals über unverschlüsseltes HTTP.
API-Authentifizierung | SilentChat