Authentifizierung

API-Schlüssel (empfohlen für Integrationen)

Ein API-Schlüssel ist ein persönliches Zugriffstoken, das an ein Mitglied Ihres Kontos gebunden ist.

• Erstellen Sie einen unter Einstellungen → Plugins → RolChat-API-Schlüssel. Das Geheimnis wird einmal angezeigt; danach sind nur seine ersten zehn Zeichen sichtbar, und RolChat speichert nur einen SHA-256-Hash.
• Format: rcp_ gefolgt von 32 zufälligen Bytes in base64url, insgesamt etwa 45 Zeichen. Das Präfix macht einen Schlüssel in Logs erkennbar und unterscheidet ihn von einem Sitzungstoken.
• Scopes: werden beim Erstellen des Schlüssels aus einem festen Katalog von Fähigkeiten gewählt. Ein Schlüssel kann nie mehr als das Mitglied, das ihn erstellt hat: Bei jedem Aufruf werden beide Bedingungen geprüft, die Fähigkeit ist in den Scopes des Schlüssels enthalten und das Mitglied besitzt sie noch. Wird die Rolle des Mitglieds eingeschränkt, schränkt sich der Schlüssel mit ein.
• Laufzeit: Schlüssel laufen nicht von selbst ab. Widerrufen Sie einen Schlüssel auf der Profilseite oder mit DELETE /api/v1/tokens/:id; der Widerruf wirkt sofort. Eine Rotation an Ort und Stelle gibt es nicht: widerrufen und einen neuen Schlüssel erstellen.
• Erstellung und Widerruf werden im Audit-Log erfasst.

Senden Sie ihn als Bearer-Token - einen separaten Header für API-Schlüssel gibt es nicht:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Anfragen mit einem Plugin-API-Schlüssel sind auf 300 pro Minute begrenzt.

JWT-Sitzungen

Die Web-App und die Mobile SDKs melden sich mit E-Mail-Adresse und Passwort (oder Google oder Apple) an und erhalten ein Token-Paar.

Token	Laufzeit	Hinweise
Access-Token	15 Minuten	RS256, geprüft gegen das JWKS unter /.well-known/jwks.json
Refresh-Token	30 Tage	Wird bei jeder Aktualisierung rotiert; die Wiederverwendung eines rotierten Tokens widerruft die gesamte Kette

Claims: sub (Nutzer), acc (Konto), rl (Rolle) und bei Rollen pro Website sts (erlaubte Websites).

POST /auth/login, /auth/refresh, /auth/swap-company und /auth/logout sind die einzigen Endpunkte des Authentifizierungsablaufs, die den im Folgenden beschriebenen Header X-Account-Id nicht enthalten dürfen.

Der Header X-Account-Id

Jede authentifizierte Anfrage außer den vier oben genannten muss das Konto angeben, in dem sie handelt:

X-Account-Id: <account uuid>

Der Server prüft, ob der Header dem Claim acc des Tokens (oder dem Konto des API-Schlüssels) entspricht. Ein fehlender Header ergibt 400 missing_required_header; eine Abweichung ergibt 403 account_context_mismatch. Den Header gibt es, damit ein Client-Fehler oder ein wiederverwendetes Token nie unbemerkt Daten eines anderen Mandanten lesen kann: Die Abweichung wird abgelehnt, bevor eine Abfrage läuft, und jede Logzeile lässt sich einem Konto zuordnen, ohne das Token zu dekodieren.

Nutzer mit mehreren Unternehmen

Eine Person kann mehreren Unternehmen angehören. Jedes Unternehmen hat sein eigenes Token (mit eigenem Claim acc). Zum Wechseln:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Das Ziel muss eines der available_companies des Aufrufers sein (bei der Anmeldung zurückgegeben), sonst 403 forbidden. Die Antwort ist ein neues Paar aus Access- und Refresh-Token für das Ziel; das alte Refresh-Token wird widerrufen, und ein Audit-Ereignis auth.account.swapped wird geschrieben.

Mehrstufige Authentifizierung

TOTP-basierte MFA kann pro Mitglied eingerichtet und pro Konto verpflichtend gemacht werden. Ist sie aktiv, liefert POST /auth/login eine Challenge, und die Sitzung wird mit POST /auth/mfa/verify abgeschlossen. Backup-Codes werden bei der Einrichtung ausgegeben.

Schutz der Anmeldung

• Anmelderouten sind auf 10 Versuche pro IP und Minute und 5 pro E-Mail-Adresse in 15 Minuten begrenzt.
• Zehn fehlgeschlagene Anmeldungen sperren die E-Mail-Adresse für 30 Minuten; die Antwort enthält code: account_locked.
• reCAPTCHA lässt sich pro Aktion aktivieren (Registrierung, Anmeldung, Passwort zurücksetzen); die öffentliche Startkonfiguration wird über GET /api/v1/captcha ausgeliefert.