Authentication: keys, scopes and rights

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#

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.

Creating a key#

1. For yourself: Settings → Interfaces.
2. For your club, association or municipality: open the organization → Manage → Interfaces. Only people with leadership rights in that organization itself see this.
3. Enter a name (stored encrypted), choose scopes, choose a validity of 1 to 365 days (default 90).
4. 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.