# Clés API

Source : https://webgune.cloud/oc-oc/docs/cles-api · Mis à jour le 2026-10-27

# Clés API

Les clés API (préfixe `wgk_`) donnent un accès programmatique à votre compte : [CLI](/docs/cli), [extension VS Code](/docs/extension-vscode), scripts CI, ou appels directs à l'[API](/docs/reference-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é

```bash
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](/docs/roles-permissions), 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` :

```bash
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.