Authentification

L'API Servolution utilise un schéma API Key simple via header HTTP X-API-Key. Chaque clé est rattachée à un user_id et à un company_id du SaaS qui l'a émise.

Format de la clé

sk_srv_<43 caractères url-safe>
exemple : sk_srv_zCmK4xT7qH1P9wYbN2eAgL5iV6oRsJ3uX8fD0pE

Préfixe sk_srv_ = "secret key Servolution". Le préfixe court (12 chars) reste visible dans votre Settings, le secret est haché en SHA-256 côté serveur — nous ne pouvons pas vous le restituer si vous le perdez.

Scopes

Chaque clé porte une liste de scopes (par défaut : ["read"]). Liste standard :

Scope	Permet
`read`	Lecture (GET)
`write`	Création / modification (POST/PATCH/PUT)
`delete`	Suppression (DELETE)
`admin`	Endpoints administratifs (super-admin du tenant)
`webhooks`	Création/lecture des endpoints webhooks
`*`	Toutes les scopes (à éviter en prod)

Quotas et rate-limiting

Tier	Quota / jour	Usage typique
Free	1 000 req	Tests, scripts d'import ponctuels
Pro	10 000 req	Sync Zapier/Make/n8n quotidienne, intégration légère
Enterprise	illimité	Connecteur ERP/CRM temps réel, marketplace

Reset à minuit UTC. Headers retournés sur chaque réponse :

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset:     43200

Expiration et rotation

Une clé peut être créée avec expires_in_days (par défaut 365). Au-delà : 401. Pour faire tourner une clé sans coupure :

Créez une nouvelle clé avec le même libellé suffixé -v2
Déployez-la sur vos systèmes
Vérifiez le last_used_at de l'ancienne clé : quand il ne bouge plus depuis 24h, révoquez-la

Révocation

curl -X DELETE https://app.commertra.servolution.fr/api/v1/api-keys/42 \
  -H "Authorization: Bearer <votre JWT user>"

Une clé révoquée renvoie immédiatement 401 sur tous les appels (vérifié à chaque requête, pas de cache).

Bonnes pratiques

Une clé par usage (script d'import ≠ webhook listener ≠ dashboard interne)
Stockez le secret dans un coffre (1Password, Vault, GitHub Actions Secrets, AWS Secrets Manager)
Ne mettez jamais une clé dans un repo public, un front JS, une variable d'environnement loggée
Rotation au minimum annuelle, immédiate si fuite suspectée
Surveillez last_used_at dans Paramètres → API Keys ; révoquez les clés inutilisées depuis 90 jours