Zum Hauptinhalt springen

Authentifizierung

Alle Anwendungs-Endpunkte unter /api sind geschützt. Anfragen müssen ein gültiges JSON Web Token (JWT) im Authorization-Header nach dem Bearer-Schema enthalten:

Authorization: Bearer <your_jwt_token>

Der project_id-Claim​

Zyles ist mandantenfähig. Jedes JWT enthält einen project_id-Claim, und das Backend beschränkt jeden Datenzugriff auf dieses Projekt:

  • Leads, Jobs, Anrufe und andere Ressourcen sind nur innerhalb ihres Projekts sichtbar.
  • Die Übergabe einer ID, die zu einem anderen Projekt gehört, liefert 401 Unauthorized zurück, nicht 404 — die API gibt nicht preis, ob die Ressource anderswo existiert.

Da das Projekt aus dem Token entnommen wird, übergeben Sie project_id niemals in Request-Bodies — es wird serverseitig abgeleitet.

Ein Token erhalten​

Tokens werden von den Authentifizierungs-Endpunkten ausgestellt (z. B. Login / Projektauswahl). Ein typischer Ablauf:

  1. Anmelden mit Benutzeranmeldedaten, um eine Benutzersitzung zu erhalten.
  2. Ein Projekt auswählen — dies liefert ein JWT zurück, das auf diese project_id beschränkt ist.
  3. Verwenden Sie dieses JWT als Bearer-Token für alle nachfolgenden API-Aufrufe.
tipp

Für lokale Tests gibt es im Backend-Repo einen mint_token-Helfer (mint_token.py), der ein signiertes JWT für ein bestimmtes Projekt ausstellt. Verwenden Sie ihn nur gegen Nicht-Produktionsumgebungen.

Beispiel-Anfrage​

curl -X POST https://backend.zyles.ai/api/leads/add \
  -H "Authorization: Bearer $ZYLES_JWT" \
  -H "Content-Type: application/json" \
  -d '[{"first_name":"John","last_name":"Doe","phone_number":"+49123456789"}]'

Fehlendes oder ungültiges Token​

Wenn der Header fehlt, fehlerhaft ist oder das Token abgelaufen ist, liefert der Endpunkt einen Fehler-Umschlag mit success: false zurück:

{
  "success": false,
  "message": "Authorization header missing"
}
{
  "success": false,
  "message": "Invalid or expired authentication token"
}

Das vollständige Fehlermodell finden Sie unter Fehler & Konventionen.