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é :

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.