Authentification API

Authentifiez-vous auprès de l'API REST sh0 en utilisant des jetons JWT Bearer ou des clés API pour un accès programmatique.

Obtenir un jeton API

Pour obtenir un jeton JWT, envoyez une requête POST à l'endpoint de connexion avec vos identifiants :

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Si les identifiants sont valides, l'API retourne un jeton JWT et les informations de l'utilisateur :

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYWJjMTIzIiwiZXhwIjoxNzE...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "Admin",
      "role": "admin"
    }
  }
}

Si l'authentification à deux facteurs est activée, incluez le code TOTP :

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "totp_code": "123456"
  }'

Authentification par jeton Bearer

Incluez le jeton JWT dans l'en-tête Authorization de chaque requête API :

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Le jeton contient l'ID utilisateur, le rôle et le délai d'expiration. sh0 valide la signature et l'expiration à chaque requête.

export SH0_TOKEN="eyJhbGciOiJIUzI1NiIs..."

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Alternative par clé API

Pour les intégrations de longue durée (pipelines CI/CD, scripts de surveillance, webhooks), les clés API sont plus pratiques que les jetons JWT car elles n'expirent pas.

Créer une clé API :

1. Naviguez vers Settings → API Keys dans le tableau de bord.
2. Cliquez sur Generate API Key.
3. Entrez un nom descriptif (ex. : "Pipeline CI/CD" ou "Surveillance").
4. Copiez la clé immédiatement -- elle n'est affichée qu'une seule fois.

Utiliser une clé API :

curl https://your-server:9000/api/apps \
  -H "X-API-Key: sh0_key_abc123def456"

Expiration et rafraîchissement des jetons

Les jetons JWT sont valides 30 jours par défaut. Le délai d'expiration est encodé dans le payload du jeton.

Pour rafraîchir un jeton expirant, appelez l'endpoint de rafraîchissement avec votre jeton actuel (encore valide) :

curl -X POST https://your-server:9000/api/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...(new token)...",
    "expires_at": "2026-04-20T12:00:00Z"
  }
}

Le tableau de bord rafraîchit automatiquement les jetons avant leur expiration. Pour les intégrations API, implémentez une logique de rafraîchissement de jeton ou utilisez des clés API pour éviter les problèmes d'expiration.

Jetons CSRF pour les requêtes du tableau de bord

Lors des requêtes depuis le tableau de bord (navigateur), sh0 utilise des jetons CSRF pour prévenir les attaques de falsification de requêtes intersites. Ceci est géré automatiquement par le client API du tableau de bord.

Si vous construisez un frontend personnalisé qui s'authentifie via des cookies (au lieu de jetons Bearer), vous devez inclure le jeton CSRF dans vos requêtes :

# Get a CSRF token
curl https://your-server:9000/api/auth/csrf-token \
  -H "Cookie: session=..."

# Include it in state-changing requests
curl -X POST https://your-server:9000/api/apps \
  -H "Cookie: session=..." \
  -H "X-CSRF-Token: csrf_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Erreurs d'authentification

Lorsque l'authentification échoue, l'API retourne une réponse d'erreur structurée :

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

Scénarios d'erreur courants :