Sécurité de l'API

L'API de Cothon est protégée par des contrôles en couches : authentification JWT, sécurité au niveau des lignes dans la base de données, stockage des jetons d'API par empreinte seulement et deux couches de limitation de débit. Cette page explique le fonctionnement de chacun et comment intégrer de façon sécuritaire.

Authentification

Sessions utilisateur (JWT)

À la connexion, Supabase Auth émet un jeton d'accès JWT (valide 1 heure) et un jeton d'actualisation. La bibliothèque cliente joint le jeton d'accès à chaque requête dans Authorization: Bearer <jeton> et l'actualise automatiquement. À chaque requête, le serveur :

• Vérifie la signature cryptographique du jeton contre une liste stricte d'algorithmes autorisés (les jetons non signés ou à algorithme détourné sont rejetés)
• Vérifie l'expiration
• Résout votre identité et vos appartenances d'organisation pour l'autorisation

Jetons d'API (accès programmatique)

Pour les scripts et intégrations, utilisez des jetons d'API plutôt que vos identifiants :

• Format : cothon_live_... — longs, cryptographiquement aléatoires et détectables par préfixe par les analyseurs de secrets
• Affichés une seule fois à la création; seule une empreinte est stockée — une fuite de base de données n'exposerait aucun jeton fonctionnel
• Limités à une organisation avec un rôle (viewer, member ou admin) et une expiration (90 jours par défaut, 365 au maximum)
• La création exige une session vérifiée par MFA; la révocation est immédiate

Pour utiliser un jeton, échangez-le contre un JWT de courte durée :

curl -X POST https://api.cothon.ca/api/v1/api-tokens/exchange \
  -H "Content-Type: application/json" \
  -d '{"token": "cothon_live_..."}'

La réponse contient un access_token valide 5 minutes (expires_in: 300); utilisez-le comme jeton Bearer et échangez de nouveau à son expiration. Le point d'échange est limité à 5 requêtes par minute pour prévenir l'énumération par force brute, et toutes les requêtes faites avec le JWT résultant s'exécutent sous la même sécurité au niveau des lignes qu'un utilisateur interactif — les jetons d'API ne contournent jamais l'isolation des données.

Hygiène des jetons : conservez-les dans des variables d'environnement ou un gestionnaire de secrets, jamais dans le code source; effectuez une rotation périodique; utilisez le rôle le plus faible qui suffit; révoquez immédiatement en cas de compromission.

Autorisation

Sécurité au niveau des lignes (RLS)

Chaque table de données client de la base PostgreSQL de Cothon comporte des politiques de sécurité au niveau des lignes qui filtrent les rangées selon les appartenances d'organisation de l'utilisateur authentifié. Cela s'exécute dans la base de données, indépendamment du code applicatif — même si un bogue laissait passer une requête, la base ne retournerait que les rangées auxquelles l'appelant a droit.

Rôles

Les permissions de l'API suivent les rôles d'organisation (propriétaire, administrateur, membre) — voir la matrice des rôles. Les points réservés aux administrateurs (journal d'audit, gestion des membres) retournent 403 aux membres.

Réponses d'erreur

Limitation de débit

Deux couches indépendantes protègent l'API :

1. Couche IP — une limite globale par adresse IP fournit une protection de base contre les abus et les attaques par déni de service
2. Couche par forfait — des limites par appelant selon le forfait de votre organisation, suivies dans Redis sur une fenêtre glissante d'une minute

En-têtes de limite de débit

Les réponses incluent des en-têtes pour cadencer votre client :

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1711800120
X-RateLimit-Plan: pro

Au dépassement de la limite, l'API retourne 429 Too Many Requests avec un en-tête Retry-After: 60 et un corps JSON précisant votre forfait et votre limite.

Gérer les 429

• Respectez Retry-After avant de réessayer
• Utilisez un recul exponentiel avec gigue pour les 429 répétés
• Surveillez X-RateLimit-Remaining et ralentissez de façon proactive à l'approche de zéro
• Si vous atteignez régulièrement les limites, passez à un forfait supérieur plutôt que de les contourner

Sécurité du transport

Tout le trafic de l'API exige HTTPS (TLS 1.2+). Les requêtes en HTTP simple ne sont pas servies. Voir l'aperçu de la sécurité pour le portrait du chiffrement au repos et en transit.

Ce que l'API n'inclut pas

Pour situer les attentes des intégrateurs : Cothon n'offre pas actuellement de webhooks sortants pour les événements de la plateforme, d'environnement bac à sable ni de jetons en mode essai, ni de quotas quotidiens. Les limites de débit sont à la minute, comme décrit ci-dessus.

Liste de vérification d'intégration

• Conserver les jetons d'API dans un gestionnaire de secrets, jamais dans le code
• Échanger les jetons contre des JWT de courte durée et gérer l'expiration de 5 minutes
• Traiter 401 par un nouvel échange, 429 par un recul selon Retry-After
• Utiliser le rôle de jeton au moindre privilège suffisant
• Définir une expiration et effectuer la rotation avant l'échéance
• Surveiller la création et la révocation des jetons dans le journal d'audit de l'organisation

Pages connexes

• Authentification et contrôle d'accès — créer et gérer les jetons d'API
• Aperçu de la sécurité et de la confidentialité — architecture et chiffrement