Developer
Die CheckCourt REST-API für eigene Integrationen
Enterprise-Feature
Die REST-API ist ein Enterprise-Feature und standardmäßig deaktiviert. Wenn du sie für deinen Verein nutzen möchtest, frag die Freischaltung beim Support an. Erst danach erscheinen die API-Schlüssel-Seiten in deiner Vereinsverwaltung.
Mit der CheckCourt REST-API bindest du deinen Verein an eigene Systeme an: ein Belegungs-Widget auf der Vereinswebsite, Buchungen aus einer Vereins-App oder der Abgleich von Mitgliedsdaten mit deiner Vereinsverwaltung.
Authentifizierung
Alle Anfragen laufen über https://app.checkcourt.de/api/v1 und brauchen
einen API-Schlüssel als Bearer-Token:
curl "https://app.checkcourt.de/api/v1/courts" \
-H "Authorization: Bearer ck_mgmt_…"Es gibt zwei Arten von Schlüsseln:
Persönliche Schlüssel (ck_user_) | Management-Schlüssel (ck_mgmt_) | |
|---|---|---|
| Wer erstellt sie? | Jedes Mitglied unter Einstellungen → API-Schlüssel | Admins unter Verwaltung → API-Schlüssel |
| Gebunden an | Den Nutzer; der Verein kommt pro Anfrage über X-Tenant-Id | Den Verein, der ihn ausgestellt hat |
| Rechte | Genau die Rechte des Mitglieds, mit der Rolle im jeweils angesprochenen Verein | Explizit ausgewählte Scopes, nicht mehr |
| Typischer Einsatz | Eigene Buchungen automatisieren, auch über mehrere Vereine | Integrationen, Widgets, Server-zu-Server |
Mehrere Vereine
Persönliche Schlüssel sind nutzergebunden. Wer in mehreren Vereinen ist,
spricht jeden Verein über denselben Schlüssel an und benennt ihn pro Anfrage
mit dem Header X-Tenant-Id; die IDs liefert GET /me/tenants (ohne
Header aufrufbar). Fehlt der Header, antwortet die API mit 400 VALIDATION.
curl "https://app.checkcourt.de/api/v1/me/tenants" \
-H "Authorization: Bearer ck_user_…"
curl "https://app.checkcourt.de/api/v1/bookings" \
-H "Authorization: Bearer ck_user_…" \
-H "X-Tenant-Id: <vereins-id>"Scopes
Management-Schlüssel bekommen beim Erstellen eine feste Liste von Scopes
(z. B. bookings:read oder members:read_confidential). Welcher
Endpoint welchen Scope braucht, steht direkt bei jedem Endpoint in der
API-Referenz. Eigene Buchungen anlegen und
stornieren funktioniert mit persönlichen Schlüsseln ohne speziellen Scope.
Fehler
Fehler haben immer dasselbe Format. Werte das Feld code aus; die
message ist deutschsprachig und kann sich ändern:
{ "error": { "code": "FORBIDDEN", "message": "Fehlende Berechtigung: bookings:read" } }| Code | HTTP | Bedeutung |
|---|---|---|
UNAUTHORIZED | 401 | Schlüssel fehlt, ist ungültig oder das Feature ist nicht freigeschaltet |
FORBIDDEN | 403 | Dem Schlüssel fehlt ein Scope oder die Berechtigung |
VALIDATION | 400 | Eingabe fehlerhaft |
NOT_FOUND | 404 | Ressource existiert nicht |
BUSINESS_RULE | 422 | Fachliche Regel verletzt (z. B. Buchungsrichtlinie) |
RATE_LIMITED | 429 | Zu viele Anfragen |
OpenAPI-Spezifikation
Die vollständige Spezifikation (OpenAPI 3.1) liefert jede Instanz
unauthentifiziert unter GET /api/v1/openapi aus, ideal, um Clients zu
generieren oder sie einem KI-Assistenten als Tool-Beschreibung zu geben.
Eine aufbereitete Ansicht findest du in der
API-Referenz.