Gestion Programmatique des Clés API

Ce guide explique comment créer, utiliser et supprimer des clés API de manière programmée en utilisant le CLI de l'API Unraid, permettant ainsi des workflows et des scripts automatisés.

Aperçu

La commande unraid-api apikey prend en charge les modes interactif et non-interactif, ce qui la rend adaptée pour :

• Scripts de déploiement automatisés
• Pipelines CI/CD
• Provisionnement d'accès temporaire
• Workflows d'infrastructure en tant que code

Quick Commencer

Aller à l'Exemple de Workflow Complet pour voir tout en action.

Création de clés API de manière programmée

Création de Base avec Sortie JSON

Utilisez l'option --json pour obtenir une sortie lisible par machine :

unraid-api apikey --create --name "workflow key" --roles ADMIN --json

Sortie :

{
    "key": "votre-clé-api-générée-ici",
    "name": "clé de workflow",
    "id": "uuid-généré"
}

Création Avancée avec Permissions

unraid-api apikey --create \
  --name "clé d'accès limité" \
  --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
  --description "Accès en lecture seule pour la surveillance" \
  --json

Gestion des Clés Existantes

Si une clé portant le même nom existe, utilisez --overwrite :

unraid-api apikey --create --name "clé existante" --roles ADMIN --overwrite --json

Key Remplacement

Le drapeau --overwrite remplacera définitivement la clef existante. L'ancienne clef sera immédiatement invalidée.

Suppression de Clés API de Manière Programmée

Suppression Non Interactive

Supprimer une clé par son nom sans invites :

unraid-api apikey --delete --name "clé de workflow"

Sortie :

Clé API supprimée avec succès

Sortie JSON pour la Suppression

Utiliser l'option --json pour obtenir une confirmation de suppression lisible par machine :

unraid-api apikey --delete --name "clé de workflow" --json

Sortie de Succès :

{
    "deleted": 1,
    "keys": [
        {
            "id": "uuid-généré",
            "name": "clé de workflow"
        }
    ]
}

Sortie d'Erreur :

{
    "deleted": 0,
    "error": "Aucune clé API trouvée avec le nom: clé inexistante"
}

Gestion des Erreurs

Quand la clé spécifiée n'existe pas :

unraid-api apikey --delete --name "clé inexistante"
# Sortie : Aucune clé API trouvée à supprimer

Sortie JSON d'Erreur :

{
    "deleted": 0,
    "message": "Aucune clé API trouvée à supprimer"
}

Exemple de Workflow Complet

Voici un exemple complet pour le provisionnement d'accès temporaire :

#!/bin/bash
set -e

# 1. Créer une clé API temporaire
echo "Création de la clé API temporaire..."
KEY_DATA=$(unraid-api apikey --create \
  --name "clé de déploiement temporaire" \
  --roles ADMIN \
  --description "Clé temporaire pour le déploiement $(date)" \
  --json)

# 2. Extraire la clé API
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "Clé API créée avec succès"

# 3. Utilisez la clé pour les opérations
echo "Configuration des services..."
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure", "clientId": "votre-client-id"}' \
  http://localhost:3001/graphql

# 4. Nettoyer (toujours exécuté, même en cas d'erreur)
trap 'echo "Nettoyage..."; unraid-api apikey --delete --name "clé de déploiement temporaire"' EXIT

echo "Déploiement terminé avec succès"

Référence de Commandes

Options de Commande de Création

Drapeau	Description	Exemple
--name <name>	Nom de la clé (requis)	--name "ma clef"
--roles <roles>	Rôles séparés par des virgules	--roles ADMIN,VIEWER
--permissions <perms>	Paires ressource:action	--permissions "DOCKER:READ_ANY"
--description <desc>	Description de la clef	--description "clé CI/CD"
--overwrite	Remplacer la clé existante	--overwrite
--json	Sortie lisible par machine	--json

Rôles Disponibles

• ADMIN - Accès complet au système
• CONNECT - Fonctionnalités Unraid Connect
• VIEWER - Accès en lecture seule
• GUEST - Accès limité

Ressources et Actions Disponibles

Ressources : ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME

Actions : CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN

Options de Commande de Suppression

Drapeau	Description	Exemple
--delete	Activer le mode suppression	--delete
--name <name>	Clé à supprimer (optionnel)	--name "ma clé"

Note : Si --name est omis, la commande s'exécute de manière interactive.

Bonnes Pratiques

Security Bonnes Pratiques

Permissions Minimales

• Utiliser des permissions spécifiques au lieu du rôle ADMIN lorsque c'est possible
• Exemple : --permissions "DOCKER:READ_ANY" au lieu de --roles ADMIN

Gestion du Cycle de Vie des Clés

• Toujours nettoyer les clés temporaires après utilisation
• Stocker les clés API de manière sécurisée (variables d'environnement, gestion des secrets)
• Utiliser des noms et descriptions descriptifs pour les traces d'audit

Gestion des Erreurs

• Vérifier les codes de sortie ($?) après chaque commande
• Utiliser set -e dans les scripts bash pour échouer rapidement
• Implémenter un nettoyage approprié avec trap

Nommer les Clés

• Utiliser des noms descriptifs incluant l'objectif et la date
• Les noms doivent contenir uniquement des lettres, des chiffres et des espaces
• Les lettres Unicode sont prises en charge

Dépannage

Problèmes courants

Common Messages d'Erreur

"Le nom de la clé API doit contenir uniquement des lettres, des chiffres et des espaces"

• Solution: Supprimer les caractères spéciaux comme les tirets, les underscores ou les symboles

"Une clé API portant le nom 'x' existe déjà"

• Solution : Utiliser l'option --overwrite ou choisir un nom différent

"Veuillez ajouter au moins un rôle ou une permission à la clé"

• Solution: Spécifier soit --roles soit --permissions (ou les deux)

Mode Débogage

Pour le dépannage, exécutez avec la journalisation du débogage :

LOG_LEVEL=debug unraid-api apikey --create --name "clé de débogage" --roles ADMIN