Skip to main content
L’API Le Commis s’authentifie avec une clé d’API par établissement, transmise dans l’en-tête HTTP X-Api-Key. Chaque requête vers https://app.lecommis.fr/api/v1 doit porter cet en-tête.

​
L’en-tête X-Api-Key

Toutes les requêtes API nécessitent l’en-tête X-Api-Key avec la clé de l’établissement concerné.
Exemple de requête
​
string
required
Clé d’API de l’établissement. La comparaison est effectuée à temps constant (SHA256 + comparaison sécurisée).
La clé est propre à un établissement : une clé donne accès aux données d’un seul établissement, identifié par son slug dans l’URL. Elle est stockée chiffrée côté Le Commis.

​
Une clé serveur-à-serveur

La clé d’API est un secret destiné à un usage serveur-à-serveur. Utilisez-la depuis votre backend (un script, un job, une fonction serverless), jamais depuis le navigateur.
N’exposez jamais votre clé d’API côté client : code JavaScript de navigateur, application mobile distribuée, dépôt Git public, variables de build front-end. Une clé exposée donne un accès en lecture aux données de votre établissement et doit être révoquée immédiatement.
Stockez la clé dans une variable d’environnement plutôt qu’en dur dans votre code.
JavaScript

​
Activation et rotation

L’API d’un établissement doit être activée pour répondre. Tant qu’elle est désactivée, tous les appels renvoient un 404 (voir ci-dessous).
Seul l’administrateur de l’établissement peut activer ou désactiver l’API et régénérer la clé. Ces actions se font depuis Réglages de l’établissement → Paramètres de l’API. Si vous ne voyez pas ces options, demandez à l’administrateur de votre établissement.
1

Activer l'API

Depuis Réglages de l’établissement → Paramètres de l’API, l’administrateur active l’API (public_api_enabled). La clé d’API y est affichée.
2

Récupérer la clé

Copiez la clé et stockez-la dans le coffre de secrets de votre backend (variable d’environnement, gestionnaire de secrets).
3

Faire tourner la clé si besoin

En cas de compromission, l’administrateur régénère la clé depuis Paramètres de l’API. L’ancienne clé est immédiatement invalidée ; pensez à mettre à jour votre backend.

​
Réponses d’authentification

​
Pourquoi un 404 et non un 403 ?

Lorsque l’API d’un établissement est désactivée (ou que le slug n’existe pas), l’API renvoie volontairement un 404 Not found — et non un 403 Forbidden.
Ce choix est délibéré : un 403 confirmerait l’existence de l’établissement. Le 404 masque l’existence de la ressource, comme s’il n’y avait rien à cette adresse. Vous ne pouvez donc pas distinguer « établissement inexistant » de « API non activée » — c’est voulu.
Concrètement :
  • 401 signale un problème de clé (absente ou invalide) sur une cible qui existe et dont l’API est activée.
  • 404 signale que la cible n’est pas accessible : slug inconnu ou API désactivée.
401 Unauthorized
404 Not found

​
Étapes suivantes

Quotas de requêtes

120 requêtes/heure par clé : comprendre et gérer les quotas de requêtes.

Gestion des erreurs

Format d’erreur et codes HTTP renvoyés par l’API.