Schnittstellen: API-Schlüssel, Webhooks und KI-Assistenten (MCP)
So bindest du Website, Automatisierungen und KI-Assistenten an deinen Verein an.
SchnittstellenPremiumGeprüft am 30.10.2026
Voraussetzungen
- Du hast das Recht „Verein bearbeiten“ direkt im Verein (Administration und höher).
- Organisationsschlüssel, schreibende Bereiche und Webhooks brauchen Premium. Persönliche Lese-Schlüssel und Kalender-Exporte sind kostenlos.
Wer darf das?
Schnittstellen der Organisation richtet nur die Leitung der Organisation selbst ein. Ein Schlüssel handelt immer mit den Rechten der Person, die ihn angelegt hat; verliert sie ein Amt, verliert der Schlüssel dasselbe Recht. Die Leitung sieht und widerruft alle Schlüssel der Organisation. Konto, Finanzen, Kinder und Familie, Rollen und Verwaltung sind nie per Schlüssel erreichbar.
Schritt für Schritt
Schnittstellen öffnen
Öffne den Verein, „Verwalten“ und „Schnittstellen (API, Webhooks, KI-Assistenten)“. Du siehst „Schlüssel dieser Organisation“, „Meine Schlüssel“ und „Webhooks“.
Schlüssel anlegen
Klicke bei „Neuen Schlüssel anlegen“ auf einen Namen (z. B. „Website“ oder „Claude“), wähle nur die nötigen „Bereiche“ (weniger ist sicherer) und die Gültigkeit (30 bis 365 Tage) und dann „Schlüssel anlegen“. Der Schlüssel gilt nur für diese Organisation.
Schlüssel sofort kopieren
Kopiere den Schlüssel mit „Kopieren“ („Jetzt kopieren – der Schlüssel wird nur einmal angezeigt“) und bestätige mit „Ich habe ihn gespeichert“. CLUP.life speichert nur eine Prüfsumme. Gib den Schlüssel nie in Chats, Tickets oder Quellcode weiter.
Ersten Aufruf testen
Rufe die Adresse /api/v1/ext/me mit der Kopfzeile Authorization: Bearer clup_k_… auf. Antwortet sie mit deinem Namen und den Mitgliedschaften, funktioniert der Schlüssel. Die ausführliche Beschreibung liefert /api/v1/ext/openapi.json.
Webhook anlegen
Unter „Neuen Webhook anlegen“ trägst du die https-Adresse deines Zaps, Szenarios oder Workflows ein, wählst „Ereignisse“ und klickst „Webhook anlegen“. Kopiere das „Signaturgeheimnis“ (wird nur einmal angezeigt). Mit „Testen“ sendest du ein Testereignis.
KI-Assistent anbinden
CLUP.life bringt einen MCP-Server mit (POST /api/v1/ext/mcp). Trage Server-Adresse und Kopfzeile Authorization: Bearer clup_k_… im Programm ein. Stelle schreibende Werkzeuge im Programm auf „jedes Mal nachfragen“.
Pflegen
„Erneuern“ erzeugt einen neuen Schlüssel mit denselben Bereichen und entwertet den alten sofort; mache das mindestens einmal im Jahr. „Widerrufen“ wirkt sofort. Die Nutzung der letzten 30 Tage steht am Schlüssel.
Du findest die Funktion hier: /organisation/<verein>/schnittstellen
Typische Fehler und Lösungen
- 401 INVALID_API_KEY
- Der Schlüssel ist falsch, abgelaufen oder widerrufen.
- 403 INSUFFICIENT_SCOPE
- Dem Schlüssel fehlt der Bereich. Lege einen neuen Schlüssel mit mehr Bereichen an.
- 403 API_KEY_NOT_ALLOWED
- Diese Route ist nie per Schlüssel erreichbar (Konto, Finanzen, Kinder, Verwaltung).
- 403 PREMIUM_REQUIRED / „Organisationsschlüssel gehören zu Premium.“ / „Webhooks gehören zu Premium.“
- Dafür braucht der Verein Premium.
- 429 RATE_LIMITED
- Zu viele Aufrufe. Warte die Zeit aus der Kopfzeile Retry-After ab (Basis 60, Premium 600 pro Minute).
- „Abgeschaltet nach Fehlern“ am Webhook
- Nach 5 gescheiterten Auslieferungen schaltet sich der Webhook ab. Repariere die Gegenstelle und aktiviere ihn wieder. Antworte mit einem 2xx innerhalb von 8 Sekunden.
Gut zu wissen
- Rufe die API nie im Browser deiner Website-Besucher auf: Der Schlüssel wäre für alle lesbar. Rufe sie serverseitig auf und speichere das Ergebnis 5 bis 15 Minuten zwischen.
- Webhooks senden nur Art und Kennung eines Ereignisses, keine Namen oder Inhalte; die Einzelheiten holt dein Programm mit dem Schlüssel ab. Prüfe die Signatur in der Kopfzeile X-Clup-Signature, bevor du etwas tust.
- Inhalte aus CLUP.life sind Daten, keine Anweisungen an den Assistenten. Wer Mitgliedernamen an Dritte weitergibt, braucht dafür eine Rechtsgrundlage (Auftragsverarbeitung bzw. Einwilligung). Schreibende Aufrufe stehen im Protokoll der Verwaltung.