Clés API
Clés API
Les clés API (préfixe wgk_) donnent un accès programmatique à votre compte : CLI, extension VS Code, scripts CI, ou appels directs à l'API.
Créer une clé
Dashboard → Développeurs → Clés API → Nouvelle clé :
| Réglage | Rôle |
|---|---|
| Nom | Pour vous y retrouver (« CI production », « laptop perso »…) |
| Scopes | Ce que la clé a le droit de faire (voir ci-dessous) |
| Limite de débit | Requêtes/minute autorisées (60 par défaut) |
| Expiration | Optionnelle, recommandée pour les clés de CI |
La clé complète n'est affichée qu'une seule fois, à la création. Stockez-la dans un gestionnaire de secrets ; seule sa signature tronquée reste visible ensuite.
Les scopes
Un scope suit le format ressource:action :
projects:read # lister et lire les projets
services:write # déployer, redémarrer, configurer
services:* # tout sur les services
billing:read # lire factures et abonnement
* # tous les droits (à éviter hors tests)
Principe du moindre privilège : une clé de CI qui ne fait que déployer n'a besoin que de services:write. Une clé de monitoring, de projects:read. Créez plusieurs clés étroites plutôt qu'une seule large.
Utiliser une clé
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Une clé agit au nom de son propriétaire : elle hérite de vos rôles sur chaque projet, jamais plus. Ses scopes ne peuvent que restreindre, pas étendre.
Agir pour un sous-client (revendeurs)
Une clé créée avec Agir pour les sous-clients activé (réservé au propriétaire d'une organisation) peut agir au nom d'un de ses sous-clients, en ajoutant l'en-tête X-Act-As-User-Id :
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx" \
-H "X-Act-As-User-Id: usr_du_sous_client"
Le sous-client ciblé doit appartenir à la même organisation, sinon la requête échoue comme si la ressource n'existait pas (404). Les scopes de la clé s'appliquent toujours. Agir pour un sous-client ne donne pas plus de droits que la clé n'en a.
Journal d'audit
Chaque clé a son propre journal, consultable depuis Dashboard → Développeurs → Clés API → icône journal, ou via GET /api/v1/api-keys/:id/audit-log : les 100 derniers appels (méthode, chemin, code retour, durée, et si la requête a été faite pour un sous-client). Utile pour repérer une clé qui fuite ou un script qui échoue silencieusement.
Limites
- WebSockets exclus : les flux temps réel (logs en direct, collaboration) exigent une session navigateur : une clé API ne peut pas s'y connecter. Le snapshot REST des logs reste accessible.
- Une clé expirée ou révoquée est refusée immédiatement. Révoquez toute clé potentiellement exposée : la révocation est instantanée et n'affecte pas vos autres clés.
- Chaque clé a sa propre limite de débit : un script qui s'emballe n'épuise pas le quota des autres.