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üssel | Organisationsschlüssel | |
|---|---|---|
| Gehört | einem Erwachsenenkonto | einer Organisation (Verein, Verband oder Kommune), angelegt von einer Person mit Leitungsrecht |
| Reichweite | alle Organisationen der Person | nur diese eine Organisation; jede andere antwortet 404 |
| Schreiben | nein, nur lesende Bereiche | ja: anlegen, ändern und löschen in den wesentlichen Bereichen (siehe Schreiben, Ändern, Löschen) |
| Stufe | Basis (kostenlos) | Premium der Organisation |
| Aktive Schlüssel | unbegrenzt | unbegrenzt |
| Anfragen/Minute | 60 | 600 |
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.
| Bereich | Erlaubt | Art | Stufe |
|---|---|---|---|
profile:read | Eigenes Konto lesen — Anzeigename und Organisationen, in denen die Person Mitglied ist | lesend | Basis |
directory:read | Vereinsverzeichnis lesen — Öffentliche Vereine, Gruppen und Verbände suchen (nur öffentliche Angaben, wie auf der Seite „Entdecken“) | lesend | Basis |
events:read | Termine lesen — Termine, die die Person ohnehin sehen darf | lesend | Basis |
events:write | Termine anlegen — Termine in der Organisation des Schlüssels anlegen (mit den Rechten der Person) | schreibend | Premium (Organisationsschlüssel) |
members:read | Mitglieder lesen — Mitgliederliste, soweit die Rolle der Person sie zeigt | lesend | Basis |
posts:read | Beiträge lesen — Beiträge einer Organisation, die die Person sehen darf | lesend | Basis |
news:read | News lesen — Öffentliche News einer Organisation (nur Beiträge der Sichtbarkeit „öffentlich“, wie im Newsfeed für die Webseite) | lesend | Basis |
announcements:read | Mitteilungen lesen — Ankündigungen und Mitteilungen der Organisation | lesend | Basis |
announcements:write | Mitteilungen senden — Mitteilungen in der Organisation des Schlüssels veröffentlichen | schreibend | Premium (Organisationsschlüssel) |
tasks:read | Aufgaben lesen — Aufgabenlisten und Aufgaben der Organisation | lesend | Basis |
tasks:write | Aufgaben anlegen — Aufgaben in der Organisation des Schlüssels anlegen (auch in einer Liste) | schreibend | Premium (Organisationsschlüssel) |
decisions:read | Beschlüsse lesen — Beschlussregister der Organisation: nur Einträge, die die Person sehen darf (Mitglieder: nur freigegebene) | lesend | Basis |
foerderung:read | Fördermöglichkeiten lesen — Fördertopfverzeichnis: nur öffentlich sichtbare Einträge mit Geber, Frist, Zielgruppe und Link zur Originalquelle; keine Förderanträge und keine Finanzdaten | lesend | Basis |
presse:read | Presse lesen — Veröffentlichte Pressemeldungen und News der Plattform (öffentliche Inhalte) | lesend | Basis |
presse:write | Presse schreiben — Pressemeldungen und News der Plattform anlegen, ändern, planen und veröffentlichen (nur Plattform-Schlüssel mit Plattformrecht) | schreibend | Premium (Organisationsschlüssel) |
exports:read | Exporte lesen — Termine als iCal/CSV/JSON, Mitgliederliste als CSV (nur mit entsprechender Rolle) | lesend | Basis |
events:delete | Termine 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, Premium | schreibend | Premium (Organisationsschlüssel) |
posts:write | Beiträge schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
posts:delete | Beiträ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, Premium | schreibend | Premium (Organisationsschlüssel) |
announcements:delete | Mitteilungen 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, Premium | schreibend | Premium (Organisationsschlüssel) |
tasks:delete | Aufgaben 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, Premium | schreibend | Premium (Organisationsschlüssel) |
polls:read | Umfragen lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
polls:write | Umfragen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
polls:delete | Umfragen 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, Premium | schreibend | Premium (Organisationsschlüssel) |
resolutions:read | Digitale Abstimmungen lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
resolutions:write | Digitale Abstimmungen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
minutes:read | Protokolle und Satzung lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
minutes:write | Protokolle und Satzung schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
minutes:delete | Protokolle 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, Premium | schreibend | Premium (Organisationsschlüssel) |
decisions:write | Beschlussregister schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
members:write | Mitglieder und Beitritte schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
offices:read | Ämter und Rollen lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
offices:write | Ämter und Rollen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (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, Premium | schreibend | Premium (Organisationsschlüssel) |
kartei:read | Karteimitglieder lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
kartei:write | Karteimitglieder schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
kartei:delete | Karteimitglieder 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, Premium | schreibend | Premium (Organisationsschlüssel) |
documents:read | Dokumente lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
documents:write | Dokumente schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
documents:delete | Dokumente 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, Premium | schreibend | Premium (Organisationsschlüssel) |
files:read | Dateiablage lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
files:write | Dateiablage schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
files:delete | Dateiablage 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, Premium | schreibend | Premium (Organisationsschlüssel) |
chronicle:read | Chronik lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
chronicle:write | Chronik schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
chronicle:delete | Chronik 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, Premium | schreibend | Premium (Organisationsschlüssel) |
awards:read | Ehrungen und Auszeichnungen lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
awards:write | Ehrungen und Auszeichnungen schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
awards:delete | Ehrungen 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, Premium | schreibend | Premium (Organisationsschlüssel) |
inventory:read | Inventar lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
inventory:write | Inventar schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
inventory:delete | Inventar 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, Premium | schreibend | Premium (Organisationsschlüssel) |
shifts:read | Dienste lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
shifts:write | Dienste schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
shifts:delete | Dienste 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, Premium | schreibend | Premium (Organisationsschlüssel) |
albums:read | Fotoalben lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
albums:write | Fotoalben schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
albums:delete | Fotoalben 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, Premium | schreibend | Premium (Organisationsschlüssel) |
matches:read | Spiele und Ergebnisse lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
matches:write | Spiele und Ergebnisse schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
matches:delete | Spiele 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, Premium | schreibend | Premium (Organisationsschlüssel) |
finance:read | Beiträge und Finanzübersicht lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
finance:write | Beiträge und Finanzübersicht schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
finance:delete | Beiträ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, Premium | schreibend | Premium (Organisationsschlüssel) |
donations:read | Spendenaufrufe lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
donations:write | Spendenaufrufe schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
donations:delete | Spendenaufrufe 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, Premium | schreibend | Premium (Organisationsschlüssel) |
grants:read | Förderung lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
grants:write | Förderung schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
grants:delete | Fö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, Premium | schreibend | Premium (Organisationsschlüssel) |
jobs:read | Stellen und Gesuche lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
jobs:write | Stellen und Gesuche schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
jobs:delete | Stellen 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, Premium | schreibend | Premium (Organisationsschlüssel) |
planner:read | Terminplaner lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
planner:write | Terminplaner schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
engagement:read | Engagement und Punkte lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
engagement:write | Engagement und Punkte schreiben — Anlegen und Ändern mit den Rechten der Person; nur Schlüssel einer Organisation, Premium | schreibend | Premium (Organisationsschlüssel) |
newskanal:read | Newskanal lesen — Lesen mit den Rechten der Person; nichts wird verändert | lesend | Basis |
Schlüssel anlegen#
- Für dich: Einstellungen → Schnittstellen.
- Für deinen Verein, Verband oder deine Kommune: Organisation öffnen → Verwalten → Schnittstellen. Das sehen nur Personen mit Leitungsrecht in dieser Organisation selbst.
- 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.
- 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 400CONFIRMATION_REQUIRED); MCP:confirm: true, Trockenlauf mitdryRun: 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-upmitscope: "apikey", Token im HeaderX-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.
