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: Termine, Mitteilungen, Aufgaben |
| Stufe | Basis (kostenlos) | Premium der Organisation |
| Aktive Schlüssel | 3 | 20 |
| 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 |
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 — Aufgaben der Gruppen | lesend | Basis |
tasks:write | Aufgaben anlegen — Aufgaben in der Organisation des Schlüssels anlegen | schreibend | Premium (Organisationsschlüssel) |
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 |
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 von 1 bis 365 Tagen (Standard 90).
- Schlüssel einmalig kopieren.
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 (höchstens 365 Tage) antwortet der Schlüssel mit 401
INVALID_API_KEY. 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.