Sviluppatori Authentication
Authentication: keys, scopes and rights
CLUP.life API keys: personal and organization keys, scopes, rotation, revocation and the rights of person, club, association and municipality.
La documentazione tecnica è disponibile in tedesco e inglese; nella tua lingua mostriamo la versione inglese.
The API knows exactly one method: an API key in the header Authorization: Bearer clup_k_…. The key consists of the prefix clup_k_ and 256 bits of randomness.
Two kinds of keys#
| Personal key | Organization key | |
|---|---|---|
| Belongs to | an adult account | one organization (club, association or municipality), created by a person with leadership rights |
| Reach | all organizations of the person | this organization only; any other answers 404 |
| Writing | no, read scopes only | yes: events, announcements, tasks |
| Tier | Basic (free) | Premium of the organization |
| Active keys | 3 | 20 |
| Requests/minute | 60 | 600 |
Rights: person, club, association, municipality#
A key has no rights of its own. On every call CLUP.life checks the rights of the person behind the key, exactly as in the app:
- Person: sees what they see in the app (events, posts and announcements of their organizations). The member list only if their role shows it.
- Club: leadership keys act with the person’s rights, e.g. creating events only with a suitable role. The leadership sees and revokes all keys of the club, even if the person who created one has left.
- Association: rights from the association apply one level weaker in sub-units (an association admin acts as moderator there). This holds for keys just as in the app.
- Municipality: like an association; public content and content of its own organization is visible.
- Not visible = 404. Organizations the key may not see answer with 404, never 403 — so their existence cannot be guessed.
If the person loses a role, the key loses the same right — immediately, because it is checked on every call.
Scopes#
A key carries only the scopes you pick when creating it. Give a program as little as possible. If a scope is missing, the API answers 403 INSUFFICIENT_SCOPE.
| Area | Consentito | Tipo | Livello |
|---|---|---|---|
profile:read | Leggere il proprio account — Nome visualizzato e organizzazioni di cui la persona è membro | lettura | Base |
directory:read | Leggere l’elenco dei club — Cerca club, gruppi e federazioni pubblici (solo informazioni pubbliche, come nella pagina Scopri) | lettura | Base |
events:read | Leggere gli eventi — Eventi che la persona può comunque vedere | lettura | Base |
events:write | Creare eventi — Creare eventi nell'organizzazione della chiave (con i diritti della persona) | scrittura | Premium (chiave dell’organizzazione) |
members:read | Leggere i membri — Elenco dei membri, nella misura in cui il ruolo della persona lo mostra | lettura | Base |
posts:read | Leggere i post — Post di un'organizzazione che la persona può vedere | lettura | Base |
announcements:read | Leggere le comunicazioni — Annunci e comunicazioni dell'organizzazione | lettura | Base |
announcements:write | Inviare comunicazioni — Pubblicare comunicazioni nell'organizzazione della chiave | scrittura | Premium (chiave dell’organizzazione) |
tasks:read | Leggere le attività — Attività dei gruppi | lettura | Base |
tasks:write | Creare attività — Creare attività nell'organizzazione della chiave | scrittura | Premium (chiave dell’organizzazione) |
presse:read | Leggere la stampa — Comunicati stampa e notizie pubblicati della piattaforma (contenuti pubblici) | lettura | Base |
presse:write | Scrivere comunicati stampa — Creare, modificare, programmare e pubblicare comunicati stampa e notizie della piattaforma (solo chiavi di piattaforma con diritto di piattaforma) | scrittura | Premium (chiave dell’organizzazione) |
exports:read | Leggere le esportazioni — Eventi come iCal/CSV/JSON, elenco dei membri come CSV (solo con il ruolo adatto) | lettura | Base |
Creating a key#
- For yourself: Settings → Interfaces.
- For your club, association or municipality: open the organization → Manage → Interfaces. Only people with leadership rights in that organization itself see this.
- Enter a name (stored encrypted), choose scopes, choose a validity of 1 to 365 days (default 90).
- Copy the key once.
Rotation, expiry and revocation#
- Renew (rotation): creates a new key with the same scopes and invalidates the old one immediately. At least once a year and at any suspicion. Only the person who created the key can renew it.
- Revoke: takes effect immediately. Revoking is never blocked, even without Premium.
- Expiry: after the chosen validity (at most 365 days) the key answers 401
INVALID_API_KEY. Plan renewal before it expires. - Account blocked or deleted: keys lose access immediately or are removed with the account.
- Usage: for each key the app shows the calls of the last 30 days (accepted/rejected). Many rejected calls point to wrong scopes or a stranger using it.
Handling keys safely#
- Keys belong in environment variables or a secret store, never in Git, chats, tickets or screenshots.
- Never call the API in your visitors’ browsers. The key would be readable by everyone. Call it on your server and cache the result for 5–15 minutes.
- We never log keys and store only a SHA-256 checksum; lost keys cannot be recovered — renew them.
- If in doubt: revoke at once, then create a new one.