API-Übersicht
Vollständige Dokumentation der Cliqer-API mit REST-Endpunkten und WebSocket-Echtzeitkommunikation.
Basis-URL
https://cliqer.io/apiAlle API-Endpunkte sind relativ zur Basis-URL des Cliqer-Servers, mit dem Sie sich verbinden.
$BASE_URL durch die URL Ihrer Cliqer-Instanz (z. B. https://cliqer.io). Ersetzen Sie in WebSocket-Beispielen $WS_URL durch wss://cliqer.io. TypeScript-Beispiele verwenden relative Pfade und funktionieren ohne Anpassung.Authentifizierung
Cliqer authentifiziert über ein httpOnly-Sitzungscookie (session_token), das von POST /api/auth/login ausgestellt wird. Browser senden es automatisch; Server-zu-Server-Tools speichern es in einem Cookie-Jar. Teams mit Studio 8K und Enterprise können zusätzlich API-Schlüssel für Server-zu-Server-REST-Anfragen erstellen, die als Authorization: Bearer cliqer_<key> gesendet werden (die Schlüsselverwaltung erfordert den Tarif Studio 8K oder Enterprise). Der WebSocket akzeptiert keine API-Schlüssel: Verbinden Sie ihn mit einem Sitzungstoken.
# The session cookie is set by /api/auth/login and sent on every subsequent request
Cookie: session_token=YOUR_SESSION_TOKEN
# Or authenticate a server-to-server REST request with a team API key
Authorization: Bearer cliqer_<key>
Einige Endpunkte benötigen keine Sitzung, etwa POST /api/licenses/validate, der öffentlich zugänglich ist.
API-Bereiche
Lebenszyklus einer Anfrage
Fehlerantworten
Alle Endpunkte geben standardisierte Fehlerantworten zurück:
| Status | Beschreibung |
|---|---|
400 | Bad Request: Fehlende oder ungültige Parameter |
401 | Unauthorized: Kein gültiges Sitzungscookie |
403 | Forbidden: Unzureichende Berechtigungen oder nicht zugelassener Origin |
404 | Not Found: Ressource nicht gefunden |
409 | Conflict: z. B. Platzlimit für die Lizenzaktivierung erreicht |
429 | Too Many Requests: Rate-Limit überschritten (siehe Retry-After) |
500 | Internal Server Error |
Format der Fehlerantwort:
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
Rate-Limiting
Die meisten Endpunkte sind pro Client-IP ratenbegrenzt, mit einem festen 60-Sekunden-Fenster in drei Stufen. Überschreitet eine Anfrage das Limit, antwortet der Server mit 429 Too Many Requests und einem Retry-After: 60-Header. Es gibt keine progressive/exponentielle Sperre, und es wird kein X-RateLimit-Remaining-Header zurückgegeben.
| Header | Beschreibung |
|---|---|
Retry-After | Sekunden bis zum Zurücksetzen des Fensters (60, nur bei einem 429 gesendet) |
Rate-Limit-Stufen
| Stufe | Anfragen / 60 s | Gilt für |
|---|---|---|
| Streng | 5 | POST /api/licenses/validate und die Anmelde-Endpunkte (POST /api/auth/login, Registrierung, Zurücksetzen des Passworts, Passkey- und 2FA-Schritte) |
| Standard | 30 | GET /api/licenses/status, POST /api/licenses/deactivate, GET /api/auth/me, POST /api/auth/logout |
| Großzügig | 60 | Lese-Endpunkte mit hohem Aufkommen |
Zwei Endpunkte wenden ein zweites Limit der Stufe Streng an, das an die Zugangsdaten statt an die IP gebunden ist, sodass ein einzelnes Ziel nicht über viele Adressen hinweg mit Anfragen überflutet werden kann: POST /api/licenses/validate verwendet dafür den license_key, POST /api/auth/login die E-Mail-Adresse.
429. Rate-Limits werden vom Server selbst durchgesetzt, bevor der Endpunkt seine Arbeit verrichtet.