Installation mit Owner-Consent

Private App oder Partner-App

1. Transaktion im Partner-Backend vorbereiten

Erzeuge code_verifier, S256-code_challenge, state, nonce und ein RSA-Schlüsselpaar mit mindestens 2.048 Bit. Speichere Private Key, Verifier und Bindungswerte verschlüsselt mit kurzer Ablaufzeit. An Padel Lab geht nur der Public JWK.

2. Club Owner autorisiert

Leite den Browser auf die zur Umgebung passende Installations-URL. Die exakte HTTPS-Redirect-URI muss für die Partner-App registriert sein. Der Owner sieht Club, Anwendung, Umgebung und Scopes vor der Zustimmung.

https://sandbox-club.padel-lab.crewio.co/developer/install
  ?application_id=<app_id>
  &environment=SANDBOX
  &scope=club%3Aread%20bookings%3Awrite
  &redirect_uri=https%3A%2F%2Fpartner.example%2Fcallback
  &state=<state>
  &nonce=<nonce>
  &code_challenge=<base64url-sha256>
  &code_challenge_method=S256
  &public_key_jwk=<urlencoded-public-jwk>

3. Callback prüfen

Akzeptiere den Callback nur, wenn genau ein code und ein konstantzeitlich passender state vorliegen. Tausche den Code ausschließlich aus demselben Backend und derselben Umgebung aus.

4. Installationscode austauschen

Der Exchange ist kein Token-Endpunkt und liefert kein Access Token. Bei einem unklaren Transportausgang wiederholst du exakt denselben Body mit demselben Idempotency-Key.

POST /v1/club/oauth/installation-exchange
Content-Type: application/json
Idempotency-Key: 018f-install-exchange

{
  "grant_type": "authorization_code",
  "code": "plc_auth_code_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  "code_verifier": "plc-verifier-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdef",
  "redirect_uri": "https://partner.example/callback"
}

5. Antwort binden und sicher speichern

Vergleiche data.nonce mit der gespeicherten Nonce. Erst danach kombinierst du oauth_subject, credential_key_id und deinen lokalen Private Key. Übernimm api_base_url, oauth_issuer, oauth_token_url, oauth_audience und oauth_audience_scope aus der Antwort als verbindliche Umgebungskonfiguration.

Berechtigungen im Club

• Nur CLUB_OWNER installiert produktiv, erweitert Scopes oder widerruft.
• CLUB_ADMIN darf Status, Nutzung und Audit-Logs lesen.
• Dynamische Client-Registrierung ist deaktiviert.
• Jede Club-/Umgebungsinstallation ist ein eigener Machine User.