CheckCourt

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.

API keysWebhooksApps
ForOne club, or a member for themselvesOne clubMany clubs and their members
Who sets it up?The club or the memberThe clubYou as the provider, the club installs
DirectionYou call CheckCourtCheckCourt calls youBoth, plus your own areas in the UI
Getting accessFeature per club, via supportFeature per club, via supportA 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 toThe user. The club is set per request via X-Tenant-IdThe club that issued it
PermissionsExactly the member's permissions from their roles in the club being addressedExplicitly selected scopes, at most the current permissions of the person who created it
Typical useAutomating your own bookings, including across several clubsIntegrations, widgets, server-to-server
Getting accessFeature api_keys_personalFeature 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.

PrefixWhatClub via X-Tenant-Id
ck_mgmt_Management keynot needed, another club returns 403
ck_user_Personal keyrequired on every club-scoped request, otherwise 400
cca_Club app token for an installationnot needed, another club returns 403
ccu_Member app tokenonly 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-based page parameter, 20 per page
  • GET /guest-fees: page and pageSize (default 25, at most 100)
  • GET /webhooks/{id}/deliveries: cursor via cursor and nextCursor

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" } }
CodeHTTPMeaning
UNAUTHORIZED401Key is missing, invalid, or the feature is not enabled
FORBIDDEN403The key lacks a scope or permission
VALIDATION400Invalid input
NOT_FOUND404Resource does not exist
BUSINESS_RULE422A business rule was violated (e.g. a booking policy)
RATE_LIMITED429Too many requests
INTERNAL500Unexpected 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.

On this page