Developers 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.
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 | Allowed | Type | Tier |
|---|---|---|---|
profile:read | Read own account — Display name and organizations the person belongs to | read | Basic |
directory:read | Read club directory — Search public clubs, groups and associations (public details only, as on the Discover page) | read | Basic |
events:read | Read events — Events the person may see anyway | read | Basic |
events:write | Create events — Create events in the key's organization (with the person's rights) | write | Premium (organization key) |
members:read | Read members — Member list, as far as the person's role shows it | read | Basic |
posts:read | Read posts — Posts of an organization that the person may see | read | Basic |
announcements:read | Read announcements — Announcements and notices of the organization | read | Basic |
announcements:write | Send announcements — Publish announcements in the key's organization | write | Premium (organization key) |
tasks:read | Read tasks — Tasks of the groups | read | Basic |
tasks:write | Create tasks — Create tasks in the key's organization | write | Premium (organization key) |
presse:read | Read press — Published press releases and news of the platform (public content) | read | Basic |
presse:write | Write press — Create, change, schedule, and publish press releases and news of the platform (platform keys with platform permission only) | write | Premium (organization key) |
exports:read | Read exports — Events as iCal/CSV/JSON, member list as CSV (only with the matching role) | read | Basic |
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.