Zum Inhalt springen
CLUP.life

Entwickler Authentifizierung

Authentifizierung: Schlüssel, Bereiche und Rechte

API-Schlüssel von CLUP.life: Personen- und Organisationsschlüssel, Bereiche (Scopes), Rotation, Widerruf und die Rechte von Person, Verein, Verband und Kommune.

Die Schnittstelle kennt genau ein Verfahren: einen API-Schlüssel im Kopf Authorization: Bearer clup_k_…. Der Schlüssel besteht aus dem Präfix clup_k_ und 256 Bit Zufall.

Zwei Arten von Schlüsseln#

PersonenschlüsselOrganisationsschlüssel
Gehörteinem Erwachsenenkontoeiner Organisation (Verein, Verband oder Kommune), angelegt von einer Person mit Leitungsrecht
Reichweitealle Organisationen der Personnur diese eine Organisation; jede andere antwortet 404
Schreibennein, nur lesende Bereicheja: anlegen, ändern und löschen in den wesentlichen Bereichen (siehe Schreiben, Ändern, Löschen)
StufeBasis (kostenlos)Premium der Organisation
Aktive Schlüsselunbegrenztunbegrenzt
Anfragen/Minute60600

Rechte: Person, Verein, Verband, Kommune#

Ein Schlüssel hat keine eigenen Rechte. Bei jedem Aufruf prüft CLUP.life die Rechte der Person hinter dem Schlüssel, genau wie in der App:

  • Person: sieht, was sie in der App sieht (Termine ihrer Organisationen, Beiträge, Mitteilungen). Die Mitgliederliste nur, wenn ihre Rolle sie zeigt.
  • Verein: Schlüssel der Leitung wirken mit den Rechten der Person, etwa Termine anlegen nur mit passender Rolle. Die Leitung sieht und widerruft alle Schlüssel des Vereins, auch wenn die Person, die ihn angelegt hat, ausgeschieden ist.
  • Verband: Rechte aus dem Verband wirken in Untergliederungen eine Stufe schwächer (ein Verbands-Admin wirkt dort als Moderator). Das gilt für Schlüssel genauso wie in der App.
  • Kommune: wie Verband; sichtbar sind öffentliche Inhalte und Inhalte der eigenen Organisation.
  • Nicht sichtbar = 404. Organisationen, die der Schlüssel nicht sehen darf, antworten mit 404, nie mit 403 — damit sich ihre Existenz nicht erraten lässt.

Verliert die Person eine Rolle, verliert der Schlüssel dasselbe Recht — sofort, denn es wird bei jedem Aufruf neu geprüft.

Bereiche (Scopes)#

Ein Schlüssel trägt nur die Bereiche, die du beim Anlegen wählst. Gib einem Programm so wenig wie möglich. Fehlt ein Bereich, antwortet die Schnittstelle mit 403 INSUFFICIENT_SCOPE.

BereichErlaubtArtStufe
profile:readEigenes Konto lesen — Anzeigename und Organisationen, in denen die Person Mitglied istlesendBasis
directory:readVereinsverzeichnis lesen — Öffentliche Vereine, Gruppen und Verbände suchen (nur öffentliche Angaben, wie auf der Seite „Entdecken“)lesendBasis
events:readTermine lesen — Termine, die die Person ohnehin sehen darflesendBasis
events:writeTermine anlegen — Termine in der Organisation des Schlüssels anlegen (mit den Rechten der Person)schreibendPremium (Organisationsschlüssel)
members:readMitglieder lesen — Mitgliederliste, soweit die Rolle der Person sie zeigtlesendBasis
posts:readBeiträge lesen — Beiträge einer Organisation, die die Person sehen darflesendBasis
news:readNews lesen — Öffentliche News einer Organisation (nur Beiträge der Sichtbarkeit „öffentlich“, wie im Newsfeed für die Webseite)lesendBasis
announcements:readMitteilungen lesen — Ankündigungen und Mitteilungen der OrganisationlesendBasis
announcements:writeMitteilungen senden — Mitteilungen in der Organisation des Schlüssels veröffentlichenschreibendPremium (Organisationsschlüssel)
tasks:readAufgaben lesen — Aufgabenlisten und Aufgaben der OrganisationlesendBasis
tasks:writeAufgaben anlegen — Aufgaben in der Organisation des Schlüssels anlegen (auch in einer Liste)schreibendPremium (Organisationsschlüssel)
decisions:readBeschlüsse lesen — Beschlussregister der Organisation: nur Einträge, die die Person sehen darf (Mitglieder: nur freigegebene)lesendBasis
foerderung:readFördermöglichkeiten lesen — Fördertopfverzeichnis: nur öffentlich sichtbare Einträge mit Geber, Frist, Zielgruppe und Link zur Originalquelle; keine Förderanträge und keine FinanzdatenlesendBasis
presse:readPresse lesen — Veröffentlichte Pressemeldungen und News der Plattform (öffentliche Inhalte)lesendBasis
presse:writePresse schreiben — Pressemeldungen und News der Plattform anlegen, ändern, planen und veröffentlichen (nur Plattform-Schlüssel mit Plattformrecht)schreibendPremium (Organisationsschlüssel)
exports:readExporte lesen — Termine als iCal/CSV/JSON, Mitgliederliste als CSV (nur mit entsprechender Rolle)lesendBasis
events:deleteTermine löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
posts:writeBeiträge schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
posts:deleteBeiträge löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
announcements:deleteMitteilungen löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
tasks:deleteAufgaben löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
polls:readUmfragen lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
polls:writeUmfragen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
polls:deleteUmfragen löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
resolutions:readDigitale Abstimmungen lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
resolutions:writeDigitale Abstimmungen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
minutes:readProtokolle und Satzung lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
minutes:writeProtokolle und Satzung schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
minutes:deleteProtokolle und Satzung löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
decisions:writeBeschlussregister schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
members:writeMitglieder und Beitritte schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
offices:readÄmter und Rollen lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
offices:writeÄmter und Rollen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
offices:deleteÄmter und Rollen löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
kartei:readKarteimitglieder lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
kartei:writeKarteimitglieder schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
kartei:deleteKarteimitglieder löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
documents:readDokumente lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
documents:writeDokumente schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
documents:deleteDokumente löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
files:readDateiablage lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
files:writeDateiablage schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
files:deleteDateiablage löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
chronicle:readChronik lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
chronicle:writeChronik schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
chronicle:deleteChronik löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
awards:readEhrungen und Auszeichnungen lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
awards:writeEhrungen und Auszeichnungen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
awards:deleteEhrungen und Auszeichnungen löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
inventory:readInventar lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
inventory:writeInventar schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
inventory:deleteInventar löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
shifts:readDienste lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
shifts:writeDienste schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
shifts:deleteDienste löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
albums:readFotoalben lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
albums:writeFotoalben schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
albums:deleteFotoalben löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
matches:readSpiele und Ergebnisse lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
matches:writeSpiele und Ergebnisse schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
matches:deleteSpiele und Ergebnisse löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
finance:readBeiträge und Finanzübersicht lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
finance:writeBeiträge und Finanzübersicht schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
finance:deleteBeiträge und Finanzübersicht löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
donations:readSpendenaufrufe lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
donations:writeSpendenaufrufe schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
donations:deleteSpendenaufrufe löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
grants:readFörderung lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
grants:writeFörderung schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
grants:deleteFörderung löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
jobs:readStellen und Gesuche lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
jobs:writeStellen und Gesuche schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
jobs:deleteStellen und Gesuche löschen — Löschen und Entfernen mit den Rechten der Person; wo es einen Papierkorb oder Storno gibt, wird er genutzt. Nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
planner:readTerminplaner lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
planner:writeTerminplaner schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
engagement:readEngagement und Punkte lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis
engagement:writeEngagement und Punkte schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, PremiumschreibendPremium (Organisationsschlüssel)
newskanal:readNewskanal lesen — Lesen mit den Rechten der Person; nichts wird verändertlesendBasis

Schlüssel anlegen#

  1. Für dich: Einstellungen → Schnittstellen.
  2. Für deinen Verein, Verband oder deine Kommune: Organisation öffnen → Verwalten → Schnittstellen. Das sehen nur Personen mit Leitungsrecht in dieser Organisation selbst.
  3. Name vergeben (er wird verschlüsselt gespeichert), Bereiche wählen, Gültigkeit wählen: 1 bis 3650 Tage (Vorschlag 365) oder unbefristet; optional erlaubte IP-Adressen eintragen.
  4. Schlüssel einmalig kopieren.

Schreiben, Ändern, Löschen#

Neben den ext/…-Routen erreicht ein Schlüssel die Plattform-Routen der Freigabeliste — dieselben Pfade wie in der App (/api/v1/organizations/{orgId}/…, /api/v1/events/{id} …). Die Referenz zeigt sie mit Bereich und MCP-Werkzeugname. Es läuft derselbe Code wie in der App: Rollen, Sichtbarkeit, Kinderregeln, Premium-Sperren und Protokoll gelten unverändert.

  • Bereiche: <bereich>:read, <bereich>:write, <bereich>:delete — Löschen ist ein eigener Bereich.
  • Nur Organisationsschlüssel dürfen schreiben und löschen. Der Schlüssel erreicht nur Ressourcen seiner Organisation; fremde antworten 404.
  • Löschen bestätigen: Header X-Clup-Confirm: delete (sonst 400 CONFIRMATION_REQUIRED); MCP: confirm: true, Trockenlauf mit dryRun: true. Wo es Papierkorb, Absagen oder Storno gibt, wird das genutzt; höchstens 5 löschende Aufrufe je MCP-Sammelanfrage.
  • Schlüssel mit Schreib- oder Löschbereich anlegen: erneute Anmeldung (POST /auth/step-up mit scope: "apikey", Token im Header X-Step-Up) und bestätigter Hinweis (acknowledgeRisk: true).
  • Nie per Schlüssel: Konto und Anmeldung, Schlüssel- und Webhook-Verwaltung, Kinder und Familie, Zahlungen, Plattformverwaltung, private Chats, Gesundheits- und Notfallangaben.

Rotation, Ablauf und Widerruf#

  • Erneuern (Rotation): erzeugt einen neuen Schlüssel mit denselben Bereichen und macht den alten sofort ungültig. Mindestens einmal im Jahr und bei jedem Verdacht. Nur die Person, die den Schlüssel angelegt hat, kann ihn erneuern.
  • Widerrufen: wirkt sofort. Widerrufen ist nie gesperrt, auch ohne Premium.
  • Ablauf: nach der gewählten Gültigkeit antwortet der Schlüssel mit 401 INVALID_API_KEY. Ein unbefristeter Schlüssel gilt, bis du ihn widerrufst; ungenutzte Schlüssel melden sich nach 90 Tagen per E-Mail. Plane die Erneuerung vor dem Ablauf ein.
  • Konto gesperrt oder gelöscht: Schlüssel verlieren sofort den Zugang bzw. entfallen mit dem Konto.
  • Nutzung: Zu jedem Schlüssel zeigt die App die Aufrufe der letzten 30 Tage (angenommen/abgewiesen). Viele abgewiesene Aufrufe deuten auf falsche Bereiche oder einen fremden Nutzer.

Sicher mit Schlüsseln umgehen#

  • Schlüssel gehören in Umgebungsvariablen oder einen Geheimnisspeicher, nie in Git, Chats, Tickets oder Screenshots.
  • Rufe die API nie im Browser deiner Besucher auf. Der Schlüssel wäre für alle lesbar. Rufe sie auf deinem Server auf und lege das Ergebnis 5–15 Minuten in den Zwischenspeicher.
  • Wir loggen keine Schlüssel und speichern nur eine SHA-256-Prüfsumme; verlorene Schlüssel lassen sich nicht wiederherstellen — erneuere sie.
  • Bei Verdacht: sofort widerrufen, dann neu anlegen.
Authentifizierung: Schlüssel, Bereiche und Rechte · CLUP.life