Clés API

Les clés API authentifient l'accès machine (scripts, cron jobs et le serveur MCP intégré) à l'API REST de Chinaski. L'accès se trouve sous Settings → API Keys (/admin/api-keys), réservé aux admins. Cette page couvre leur création, leur scoping et leur révocation ; le modèle de requêtes (scopes, rate limits) a sa propre page Automatisation.

Créer une clé

• Cliquez sur create ; donnez à la clé un nom (obligatoire ; les noms sont les identifiants d'audit éternels) et une permission :
  • read : peut récupérer du contenu mais jamais le modifier.
  • write : peut créer et mettre à jour ; requis pour chaque appel modifiant des données.
• Définissez éventuellement une date d'expiration (une simple date ; laisser vide signifie que la clé n'expire jamais).
• La clé elle-même est une longue chaîne aléatoire générée par une source aléatoire sécurisée, affichée exactement une fois dans un champ de copie juste après la création, avec une note explicite indiquant qu'elle ne sera plus jamais affichée. Seul un hash est stocké (et pour les clés nouvellement créées, une couche de vérification bcrypt par-dessus), donc une base de données divulguée ne peut pas révéler de clés actives.
• Les créations sont auditées (l'action nomme la clé et son scope).

Le scoping en pratique

• Cards regroupe lecture/écriture par flux : le scope read ne peut rien créer ni modifier.
• Le scope write est requis pour chaque endpoint manipulant du contenu, tant pour les chemins « sûrs » qu'administratifs, une clé créée comme reporter en lecture seule ne peut donc pas se faufiler par une route moins connue.
• Une large porte d'assertion devant les routes authentifiées par session vérifie désormais le scope par méthode, de sorte que les appels en écriture avec des clés read obtiennent un 403 propre plutôt qu'une fuite de permissions silencieuse.

Limitation de débit

Le rate limiting est par clé, par fenêtre glissante de 60 secondes, avec 100 requêtes par minute par défaut (configurable dans Settings → Security : « API key rate limit »). Dépasser la limite renvoie une réponse 429 avec un en-tête Retry-After indiquant au script combien de temps attendre. Chaque requête incrémente le compteur exactement une fois, quel que soit le nombre de couches d'authentification internes traversées.

Retour d'usage des clés : chaque clé enregistre la dernière fois qu'elle s'est authentifiée ; l'usage récent est visible sur l'écran des clés, et chaque requête est auditée (méthode et chemin), ce qui est le moyen le plus rapide de trouver les clés abandonnées.

Le kill switch

Le toggle maître « API access » sur le même écran désactive toutes les requêtes API d'un seul interrupteur. Avec l'accès désactivé, l'API répond à chaque requête par un 503, en ignorant les clés, pratique pendant les incidents sans devoir passer en revue votre liste de clés. L'action du toggle elle-même est auditée avec l'état obtenu.

Révocation

Supprimer une clé est instantané et audité : la clé cesse de fonctionner immédiatement après. L'habitude de nettoyage la plus sûre : la piste d'audit trouve les dates de dernière utilisation par clé ; une clé avec un timestamp de dernière utilisation obsolète et une origine de test constitue une politique de retraite bien ordonnée.