API-Referenz

Interaktive Dokumentation

Clavis stellt zwei interaktive API-Dokumentationen bereit:

URL	Beschreibung
/api/docs	Swagger UI — interaktive API-Explorer
/api/redoc	ReDoc — lesbare, zweispaltige Ansicht

Beide sind aus der OpenAPI-Spezifikation generiert und spiegeln die tatsächlich vorhandenen Endpunkte wider.

Authentifizierung

JWT-Bearer (interne Nutzer)

Für angemeldete Nutzer (Koordinatoren, Ersteller, Admins):

Authorization: Bearer <access_token>

Das Token wird beim Login (POST /api/auth/login) zurückgegeben.

Cookie-Auth (Teilnehmer)

Für Gäste und Teilnehmer werden Session-Cookies verwendet (gesetzt beim Join-Flow). Kein manueller Header erforderlich.

WebSocket-Token

Für WebSocket-Verbindungen muss zunächst ein kurzlebiges WS-Token abgerufen werden:

GET /api/auth/ws-token
Authorization: Bearer <access_token>

Das WS-Token wird als Query-Parameter übergeben.

WebSocket-Endpunkte

Endpunkt	Beschreibung
GET /api/orgs/{slug}/runs/{run_id}/ws	Koordinator-Stream: Run-State-Updates, Team-Events, Feed
GET /api/orgs/{slug}/runs/{run_id}/teams/{team_id}/ws	Team-Stream: Submissions, Chat, Feed, Run-State

Verbindungsaufbau

const wsToken = await fetch('/api/auth/ws-token', {
  headers: { Authorization: `Bearer ${accessToken}` }
}).then(r => r.json()).then(d => d.token);

const ws = new WebSocket(
  `wss://app.clavis-rallye.com/api/orgs/${slug}/runs/${runId}/ws?token=${wsToken}`
);

Wichtige Endpunkte (Übersicht)

Methode	Pfad	Beschreibung
POST	/api/auth/login	Login; gibt JWT zurück
POST	/api/auth/refresh	Token erneuern
GET	/api/auth/ws-token	WS-Token für WebSocket-Auth
GET	/api/health	Gesundheitsstatus der Dienste
GET	/api/orgs/{slug}/rallyes	Rallye-Liste
POST	/api/orgs/{slug}/runs	Neuen Lauf erstellen
POST	/api/orgs/{slug}/runs/{run_id}/join	Gast-Join-Flow
POST	/api/orgs/{slug}/runs/{run_id}/teams/{team_id}/submissions	Einreichung erstellen

Die vollständige Endpunktliste mit Parametern und Antwortformaten ist unter /api/docs verfügbar.

Mandantenisolation

Alle Endpunkte sind durch den {slug} der Organisation isoliert. Ein Nutzer kann nur auf Ressourcen seiner eigenen Organisation zugreifen. Cross-Tenant-Zugriff wird serverseitig abgelehnt.