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 :

Création de clés API

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

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

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

Sortie :

{
    "key": "your-generated-api-key-here",
    "name": "workflow key",
    "id": "generated-uuid"
}

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

unraid-api apikey --create \
  --name "limited access key" \
  --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
  --description "Read-only access for monitoring" \
  --json

Sortie :

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

unraid-api apikey --create --name "existing key" --roles ADMIN --overwrite --json

avertissement

Supprimer une clé par son nom sans invites :

Suppression de clés API

Supprimer une clé par son nom sans invites :

Supprimer une clé par son nom sans invites :

unraid-api apikey --delete --name "workflow key"

Sortie :

Successfully deleted 1 API key

Supprimer une clé par son nom sans invites :

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

unraid-api apikey --delete --name "workflow key" --json

Sortie de Succès :

{
    "deleted": 1,
    "keys": [
        {
            "id": "generated-uuid",
            "name": "workflow key"
        }
    ]
}

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

{
    "deleted": 0,
    "error": "No API key found with name: nonexistent key"
}

Sortie de Succès :

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

unraid-api apikey --delete --name "nonexistent key"
# Output: No API keys found to delete

Sortie JSON d'Erreur :

{
    "deleted": 0,
    "message": "No API keys found to delete"
}

Exemple de workflow complet

Sortie JSON d'Erreur :

#!/bin/bash
set -e

# 1. Create temporary API key
echo "Creating temporary API key..."
KEY_DATA=$(unraid-api apikey --create \
  --name "temp deployment key" \
  --roles ADMIN \
  --description "Temporary key for deployment $(date)" \
  --json)

# 2. Extract the API key
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "API key created successfully"

# 3. Use the key for operations
echo "Configuring services..."
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure", "clientId": "your-client-id"}' \
  http://localhost:3001/graphql

# 4. Clean up (always runs, even on error)
trap 'echo "Cleaning up..."; unraid-api apikey --delete --name "temp deployment key"' EXIT

echo "Deployment completed successfully"

Référence de commande

Options de la commande de création :

Option	Description	Exemple
--name <name>	Nom de la clé (requis)	--name "ma clé"
--rôles <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 clé	--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 disponibles : 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 disponibles : CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN.

Options de la commande de suppression :

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

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

Utilisez des permissions spécifiques plutôt que le rôle ADMIN lorsque c'est possible (par exemple, --permissions "DOCKER:READ_ANY" au lieu de --roles ADMIN). Nettoyez toujours les clés temporaires après utilisation et stockez les clés API en toute sécurité (variables d'environnement, gestion des secrets). Utilisez des noms descriptifs incluant l'objectif et la date pour les pistes d'audit. Notez que les noms ne doivent contenir que des lettres, des chiffres et des espaces (les lettres Unicode sont prises en charge).

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

Dépannage

Messages d'erreur courants:

• "Le nom de la clé API doit contenir uniquement des lettres, des chiffres et des espaces" : supprimez les caractères spéciaux comme les tirets, les underscores ou les symboles.
• "Une clé API portant le nom 'x' existe déjà" : utilisez l'option --overwrite ou choisissez un nom différent.
• "Veuillez ajouter au moins un rôle ou une permission à la clé" : spécifiez --roles ou --permissions (ou les deux).

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

LOG_LEVEL=debug unraid-api apikey --create --name "debug key" --roles ADMIN