API publique KOMUNITYA

Base URL : https://komunitya.com/api/v1

1. Système de clés (style Stripe)

KOMUNITYA utilise un système à double clé, comme Stripe :

Type	Préfixe	Usage	Permissions
Clé publique	kmtpklive_*	Front-end / SPA / mobile	Lecture seule
Clé secrète	kmtsklive_*	Back-end / serveur	Lecture + écriture

En développement, les préfixes deviennent kmtpktest* et kmtsktest*.

Règle d'or : la clé secrète ne doit JAMAIS apparaître dans du code envoyé au navigateur ou dans un dépôt Git public. Utilisez des variables d'environnement.

2. Créer une paire de clés

1. Allez sur Profil → Clés API
2. Cliquez Nouvelle paire de clés
3. Donnez un nom (Mon CRM, App mobile…)
4. Sélectionnez les scopes (la clé publique ne reçoit que les scopes en lecture)
5. Optionnel — Origines CORS autorisées pour la clé publique (recommandé)
6. Générer

⚠️ Les deux clés ne sont affichées qu'UNE FOIS. Copiez-les immédiatement.

3. Premier appel — depuis un serveur (clé secrète)

curl https://komunitya.com/api/v1/groups \
  -H "Authorization: Bearer kmt_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

4. Premier appel — depuis le navigateur (clé publique)

fetch("https://komunitya.com/api/v1/groups", {
  headers: { Authorization: "Bearer kmt_pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
}).then(r => r.json()).then(console.log)

Réponse :

{
  "data": [
    { "id": "...", "name": "...", "memberCount": 42 }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

5. Pagination

Utilisez ?limit=20&cursor=<id>. La réponse contient pagination.nextCursor et pagination.hasMore.

6. Rate limit

• Clé publique : 120 req/min par défaut
• Clé secrète : 60 req/min par défaut

Headers de réponse :

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

7. CORS / Sécurité front-end

Pour les clés publiques utilisées côté navigateur, configurez la liste des origines autorisées dans Profil → Clés API → [paire] → Modifier.

Une origine = scheme + host + port (ex: https://monsite.com). Une par ligne. Laissez vide pour autoriser tout le monde (déconseillé en production).

8. Spec OpenAPI

GET /api/v1/openapi.json — utilisable dans Postman, Insomnia, Swagger UI, Scalar.

9. Que faire en cas de fuite ?

1. Révoquez immédiatement la clé compromise depuis le dashboard
2. Régénérez une nouvelle paire
3. Mettez à jour vos services
4. Auditez les logs API (Profil → Clés API → Audit)