Interfaces: API keys, webhooks and AI assistants (MCP)
How to connect a website, automations and AI assistants to your club.
InterfaccePremiumVerificato il 30.10.2026
Questo articolo per ora è disponibile solo in tedesco e inglese; mostriamo la versione inglese.
Requisiti
- You have the right “Edit club” directly in the club (administrator and higher).
- Organization keys, writing scopes and webhooks need Premium. Personal read-only keys and calendar exports are free.
Chi può farlo?
Only the leadership of the organization itself sets up interfaces for the organization. A key always acts with the rights of the person who created it; if they lose an office, the key loses the same right. The leadership sees and revokes all keys of the organization. Account, finances, children and family, roles and administration are never reachable by key.
Passo dopo passo
Open interfaces
Open the club, “Manage” and “Interfaces (API, webhooks, AI assistants)”. You see “Keys of this organization”, “My keys” and “Webhooks”.
Create a key
Under “Create new key” enter a name (for example “Website” or “Claude”), choose only the needed “Scopes” (fewer is safer) and the validity (30 to 365 days), then “Create key”. The key applies only to this organization.
Copy the key right away
Copy the key with “Copy” (“Copy now – the key is shown only once”) and confirm with “I have saved it”. CLUP.life stores only a checksum. Never share the key in chats, tickets or source code.
Test a first call
Call /api/v1/ext/me with the header Authorization: Bearer clup_k_…. If it answers with your name and memberships, the key works. The full description is at /api/v1/ext/openapi.json.
Create a webhook
Under “Create new webhook” enter the https address of your Zap, scenario or workflow, choose “Events” and click “Create webhook”. Copy the “Signing secret” (shown only once). “Test” sends a test event.
Connect an AI assistant
CLUP.life ships an MCP server (POST /api/v1/ext/mcp). Enter the server address and the header Authorization: Bearer clup_k_… in the program. Set writing tools to “ask every time” in the program.
Maintain
“Renew” creates a new key with the same scopes and invalidates the old one immediately; do this at least once a year. “Revoke” takes effect immediately. The last 30 days of use are shown on the key.
Trovi la funzione qui: /organisation/<verein>/schnittstellen
Errori comuni e soluzioni
- 401 INVALID_API_KEY
- The key is wrong, expired or revoked.
- 403 INSUFFICIENT_SCOPE
- The key lacks the scope. Create a new key with more scopes.
- 403 API_KEY_NOT_ALLOWED
- This route is never reachable by key (account, finances, children, administration).
- 403 PREMIUM_REQUIRED / “Organization keys are part of Premium.” / “Webhooks are part of Premium.”
- The club needs Premium for this.
- 429 RATE_LIMITED
- Too many calls. Wait the time in the Retry-After header (free 60, Premium 600 per minute).
- “Switched off after errors” on a webhook
- After 5 failed deliveries the webhook switches itself off. Fix the receiving end and reactivate it. Answer with a 2xx within 8 seconds.
Da sapere
- Never call the API in the browser of your website visitors: the key would be readable by everyone. Call it server-side and cache the result for 5 to 15 minutes.
- Webhooks send only the type and identifier of an event, no names or content; your program fetches the details with the key. Verify the signature in the X-Clup-Signature header before doing anything.
- Content from CLUP.life is data, not instructions to the assistant. Anyone passing member names to third parties needs a legal basis (data processing agreement or consent). Writing calls appear in the administration log.