Développeurs 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 documentation technique existe en allemand et en anglais ; dans votre langue, nous affichons la version anglaise.
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.
| Domaine | Autorisé | Type | Niveau |
|---|---|---|---|
profile:read | Lire son propre compte — Nom affiché et organisations dont la personne est membre | lecture | Base |
directory:read | Lire l’annuaire des clubs — Rechercher des clubs, groupes et fédérations publics (informations publiques uniquement, comme sur la page Découvrir) | lecture | Base |
events:read | Lire les événements — Événements que la personne a de toute façon le droit de voir | lecture | Base |
events:write | Créer des événements — Créer des événements dans l'organisation de la clé (avec les droits de la personne) | écriture | Premium (clé d’organisation) |
members:read | Lire les membres — Liste des membres, dans la mesure où le rôle de la personne l'affiche | lecture | Base |
posts:read | Lire les publications — Publications d'une organisation que la personne a le droit de voir | lecture | Base |
announcements:read | Lire les annonces — Annonces et communications de l'organisation | lecture | Base |
announcements:write | Envoyer des annonces — Publier des annonces dans l'organisation de la clé | écriture | Premium (clé d’organisation) |
tasks:read | Lire les tâches — Tâches des groupes | lecture | Base |
tasks:write | Créer des tâches — Créer des tâches dans l'organisation de la clé | écriture | Premium (clé d’organisation) |
presse:read | Lire la presse — Communiqués de presse et actualités publiés de la plateforme (contenus publics) | lecture | Base |
presse:write | Rédiger la presse — Créer, modifier, planifier et publier les communiqués de presse et actualités de la plateforme (uniquement clés de plateforme disposant du droit de plateforme) | écriture | Premium (clé d’organisation) |
exports:read | Lire les exports — Événements en iCal/CSV/JSON, liste des membres en CSV (uniquement avec le rôle approprié) | lecture | 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.