Geliştiriciler 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.
Teknik belgeler Almanca ve İngilizce sunulur; dilinizde İngilizce sürümü gösteriyoruz.
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.
| Alan | İzin verilen | Tür | Seviye |
|---|---|---|---|
profile:read | Kendi hesabını oku — Görünen ad ve kişinin üye olduğu kuruluşlar | okuma | Temel |
directory:read | Kulüp rehberini oku — Herkese açık kulüpleri, grupları ve birlikleri ara (yalnızca herkese açık bilgiler, Keşfet sayfasındaki gibi) | okuma | Temel |
events:read | Etkinlikleri oku — Kişinin zaten görebileceği etkinlikler | okuma | Temel |
events:write | Etkinlik oluştur — Anahtarın kuruluşunda etkinlik oluştur (kişinin yetkileriyle) | yazma | Premium (kuruluş anahtarı) |
members:read | Üyeleri oku — Kişinin rolü izin verdiği ölçüde üye listesi | okuma | Temel |
posts:read | Gönderileri oku — Kişinin görebileceği bir kuruluşun gönderileri | okuma | Temel |
announcements:read | Duyuruları oku — Kuruluşun duyuruları ve bildirimleri | okuma | Temel |
announcements:write | Duyuru gönder — Anahtarın kuruluşunda duyuru yayınla | yazma | Premium (kuruluş anahtarı) |
tasks:read | Görevleri oku — Grupların görevleri | okuma | Temel |
tasks:write | Görev oluştur — Anahtarın kuruluşunda görev oluştur | yazma | Premium (kuruluş anahtarı) |
presse:read | Basını oku — Platformun yayımlanmış basın bültenleri ve haberleri (herkese açık içerikler) | okuma | Temel |
presse:write | Basın yaz — Platformun basın bültenlerini ve haberlerini oluşturma, değiştirme, planlama ve yayımlama (yalnızca platform yetkisi olan platform anahtarları) | yazma | Premium (kuruluş anahtarı) |
exports:read | Dışa aktarımları oku — iCal/CSV/JSON olarak etkinlikler, CSV olarak üye listesi (yalnızca uygun rolle) | okuma | Temel |
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.