Authentification API

Tous les points d’entrée REST vivent sous /api/v1. Les scripts, les tâches de CI et les intégrations s’authentifient avec une clé d’API ; le tableau de bord utilise une session par cookie.

Clés d’API

Une clé d’API est le seul identifiant prévu pour les programmes. Créez-en une par outil : vous pourrez révoquer une intégration sans toucher aux autres.

1. Dans le tableau de bord, ouvrez Paramètres → Clés API et cliquez sur Créer une clé API.
2. Donnez-lui un nom qui dit ce qui l’utilise, par exemple « Pipeline CI ».
3. Choisissez son niveau d’accès et, si vous le souhaitez, une date d’expiration.
4. Copiez la clé tout de suite : elle n’est affichée qu’une fois et stockée sous forme hachée. Si vous la perdez, supprimez-la et créez-en une nouvelle.

Les clés commencent par sh0_. Une clé ne peut jamais faire plus que le compte qui l’a créée, et une clé ne peut pas créer d’autres clés.

Niveaux d’accès

Chaque clé porte l’un des trois niveaux d’accès, appliqué par le serveur à chaque requête. Par l’API, le niveau est le champ scopes : read, deploy ou admin.

Utiliser une clé

Envoyez la clé dans l’en-tête Authorization: Bearer de chaque requête :

export SH0_TOKEN="sh0_..."
curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Sessions du tableau de bord

Le tableau de bord se connecte avec POST /api/v1/auth/login. En cas de succès, le serveur pose des cookies HttpOnly (sh0_access et sh0_refresh) et renvoie un csrf_token dans le corps de la réponse ; aucun jeton n’est renvoyé dans le corps. Ce parcours est fait pour les navigateurs : pour un script, utilisez une clé d’API.

La session d'accès dure 24 heures. Le tableau de bord la renouvelle par POST /api/v1/auth/refresh, qui émet aussi une nouvelle session de renouvellement de 30 jours ; une session inutilisée pendant 30 jours prend fin.

Changer de mot de passe déconnecte toutes les autres sessions. Les tentatives de connexion sont limitées à 5 échecs par 15 minutes ; un mot de passe correct ne compte pas dans la limite.

Connexion à deux facteurs

Quand le compte a la double authentification, la connexion répond requires_totp avec un totp_nonce de courte durée au lieu d’ouvrir la session. Le client envoie ensuite ce nonce et le code à 6 chiffres (ou un code de secours) à POST /api/v1/auth/totp/verify. La vérification est limitée à 5 essais par 5 minutes.

Protection CSRF

Les requêtes authentifiées par le cookie de session doivent répéter le jeton CSRF dans l’en-tête X-CSRF-Token à chaque appel qui modifie un état. Les requêtes authentifiées par une clé d’API dans l’en-tête Authorization n’en ont pas besoin.

Erreurs d’authentification

Les erreurs utilisent l’enveloppe d’erreur standard. Par exemple, une clé inconnue ou révoquée :

{"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}