Developer
Connect CheckCourt to your own systems via the REST API, webhooks or as an app for many clubs
There are three ways to connect CheckCourt to other systems. Which one fits depends on whether you are building something for your own club or for many.
REST API with an API key
For your own club: occupancy widget, sync with club administration software, scripts
Webhooks
CheckCourt reports bookings, membership changes and court locks instantly to an address of your choice
Apps
For many clubs: door locks, floodlights, accounting, calendar sync, with marketplace and review
API reference
All endpoints with parameters, scopes and examples
| API keys | Webhooks | Apps | |
|---|---|---|---|
| For | One club, or a member for themselves | One club | Many clubs and their members |
| Who sets it up? | The club or the member | The club | You as the provider, the club installs |
| Direction | You call CheckCourt | CheckCourt calls you | Both, plus your own areas in the UI |
| Getting access | Feature per club, via support | Feature per club, via support | A developer organization, by sign-up or invitation |
The rest of this page covers the basics of the REST API with API keys. Apps use the same endpoints but their own tokens, see API for apps.
Getting access
Enterprise feature
API keys are an enterprise feature and disabled by default. If you want to use them for your club, ask support to enable them. Only then do management keys appear under Admin → Automatisierungen (automations) and personal keys under Einstellungen → Meine API-Schlüssel (Settings → My API keys).
Authentication
All requests go to https://app.checkcourt.de/api/v1 and need
a key as a bearer token:
curl "https://app.checkcourt.de/api/v1/courts" \
-H "Authorization: Bearer ck_mgmt_…"There are two kinds of API keys:
Personal keys (ck_user_) | Management keys (ck_mgmt_) | |
|---|---|---|
| Who creates them? | Every member under Einstellungen → Meine API-Schlüssel (Settings → My API keys) | Admins under Admin → Automatisierungen (automations), section API-Schlüssel (API keys) |
| Bound to | The user. The club is set per request via X-Tenant-Id | The club that issued it |
| Permissions | Exactly the member's permissions from their roles in the club being addressed | Explicitly selected scopes, at most the current permissions of the person who created it |
| Typical use | Automating your own bookings, including across several clubs | Integrations, widgets, server-to-server |
| Getting access | Feature api_keys_personal | Feature api_keys_management |
If the feature is off for the club, the API rejects the key with 401 UNAUTHORIZED.
Apps use their own short-lived tokens that are valid for one hour. How they are issued is described in Authentication for apps.
| Prefix | What | Club via X-Tenant-Id |
|---|---|---|
ck_mgmt_ | Management key | not needed, another club returns 403 |
ck_user_ | Personal key | required on every club-scoped request, otherwise 400 |
cca_ | Club app token for an installation | not needed, another club returns 403 |
ccu_ | Member app token | only needed if the app is connected in several clubs, otherwise 400; a club without a connection returns 403 |
Refresh tokens (ccr_…) are not bearer tokens. Sent as a bearer, the API always responds
with 401. Exchange them at POST /api/oauth/token instead.
Multiple clubs
Personal keys are bound to the user. If you belong to several clubs, you address every
club with the same key and name it per request with the X-Tenant-Id header. GET /me/tenants returns the IDs (callable without the header). If the header is missing, the
API responds with 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: <club-id>"Scopes
Management keys get a fixed list of scopes when they are created
(e.g. bookings:read or members:read_confidential). Which scope an endpoint
needs is listed with each endpoint in the
API reference. GET /permissions returns the full
catalog with German labels. Creating and cancelling your own bookings works with personal
keys without any special scope.
Only a personal key can change roles (roles:manage), never a management key. Assigning
roles decides what people are allowed to do, and that takes a person.
Pagination
Successful responses are always JSON objects with named fields. Lists that can grow without limit are paginated:
GET /members: 1-basedpageparameter, 20 per pageGET /guest-fees:pageandpageSize(default 25, at most 100)GET /webhooks/{id}/deliveries: cursor viacursorandnextCursor
All other lists return the complete set.
Errors
Errors always have the same format. Evaluate the code field. The
message is in German and can change:
{ "error": { "code": "FORBIDDEN", "message": "Fehlende Berechtigung: bookings:read" } }| Code | HTTP | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Key is missing, invalid, or the feature is not enabled |
FORBIDDEN | 403 | The key lacks a scope or permission |
VALIDATION | 400 | Invalid input |
NOT_FOUND | 404 | Resource does not exist |
BUSINESS_RULE | 422 | A business rule was violated (e.g. a booking policy) |
RATE_LIMITED | 429 | Too many requests |
INTERNAL | 500 | Unexpected error at CheckCourt |
For a BUSINESS_RULE error caused by a booking policy, the error also contains
canOverride. If it is true, the request succeeds with bookings:write or
bookings:cancel when you repeat it with adminOverride: true in the body or
?override=true, respectively.
Rate limits
The API allows 60 requests per minute per IP address and additionally
120 requests per minute per credential, even if the requests come from many addresses.
A credential is an API key, an installation of a club app (cca_), or a member app per
member (ccu_). Above that, the API responds with 429 RATE_LIMITED
and the Retry-After header tells you after how many seconds you can try again.
OpenAPI specification
Every instance serves the complete specification (OpenAPI 3.1) without authentication
at GET /api/v1/openapi, ideal for generating clients or handing it to an AI assistant
as a tool description. A rendered view is available in the
API reference.