Die erste sichere Anfrage

Bevor du startest

Die Club API ist für serverseitige Club- und Partnersysteme gebaut.

• Verwende für Entwicklung ausschließlich die Sandbox mit synthetischen Testdaten.
• Halte Private Keys, Assertions und Access Tokens in deinem Backend oder Secret Vault.
• Eine Installation ist immer an genau einen Club, eine Anwendung und eine Umgebung gebunden.
• Beginne mit den kleinsten benötigten Scopes; Erweiterungen muss ein Club Owner erneut freigeben.

Umgebungen

Access Token beziehen

Jede Installation erhält einen eigenen ZITADEL Machine User. Signiere eine kurze RS256-Assertion mit dem privaten Schlüssel deiner Installation und tausche sie über den gelieferten oauth_token_url gegen ein Access Token.

Verwende immer die Werte aus der verifizierten Installationsantwort. Sandbox- und Produktions-Issuer dürfen nicht vermischt werden.

POST /oauth/v2/token HTTP/1.1
Host: <oauth-host-aus-installation>
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
scope=openid%20<oauth_audience_scope>&
assertion=<RS256-private-key-jwt>

Installation und Club prüfen

GET /context ist der erste fachliche Request. Die Antwort bestätigt, welchen Club, welche Anwendung, welche Umgebung und welche aktuell wirksamen Scopes dein Token repräsentiert.

curl 'https://sandbox-api.padel-lab.crewio.co/v1/club/context' \
  --header "Authorization: Bearer $PADEL_LAB_TOKEN"

{
  "data": {
    "installation": {
      "id": "inst_…",
      "application_id": "app_…",
      "environment": "SANDBOX",
      "status": "ACTIVE",
      "scopes": ["club:read", "courts:read", "bookings:write"],
      "installed_at": "2030-01-15T16:00:00.000Z",
      "expires_at": null
    },
    "application": {"id": "app_…", "slug": "booking-sync", "name": "Booking Sync"},
    "club": {
      "id": "org_…",
      "slug": "synthetic-club",
      "name": "Synthetic Club",
      "status": "ACTIVE",
      "timezone": "Europe/Berlin",
      "currency": "EUR",
      "country": "DE",
      "language": "de"
    }
  }
}

Danach

• Lege eine stabile Buchungsquelle für das externe Konto an.
• Lies Courts und speichere explizite Court-Mappings.
• Importiere den Erstbestand in Jobs mit höchstens 500 Buchungen.
• Übermittle anschließend vollständige Snapshots mit steigender source_version.
• Speichere Event-IDs dauerhaft und verbinde Replay mit WebSocket oder Webhooks.