Gestión programática de Claves API

Esta guía explica cómo crear, usar y eliminar claves API programáticamente usando el CLI de la API de Unraid, permitiendo flujos de trabajo automatizados y scripts.

Visión General

El comando unraid-api apikey admite modos tanto interactivos como no interactivos, lo que lo hace adecuado para:

Creación de claves API

Salte a la Ejemplo Completo del Flujo de Trabajo para ver todo en acción.

Salida:

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

Salida:

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

Salida:

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

Salida:

Si ya existe una clave con el mismo nombre, use --overwrite:

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

advertencia

Reemplazar Clave Existente

Eliminación de claves API

Reemplazar Clave Existente

Eliminar una clave por nombre sin confirmaciones:

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

Salida:

Successfully deleted 1 API key

Eliminar una clave por nombre sin confirmaciones:

Utilice la bandera --json para obtener confirmación de eliminación legible por máquina:

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

Salida de Éxito:

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

Salida de Error:

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

Salida de Éxito:

Cuando la clave especificada no existe:

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

Salida de Error en JSON:

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

Ejemplo completo de flujo de trabajo

Salida de Error en JSON:

#!/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"

Ejemplo Completo de Flujo de Trabajo

Aquí hay un ejemplo completo para la provisión de acceso temporal:

Bandera	Descripción	Ejemplo
--name <name>	Nombre de la clave (requerido)	--name "mi clave"
--roles <roles>	Roles separados por comas	--roles ADMIN,VIEWER
--permissions <perms>	Pares de recurso:acción	--permissions "DOCKER:READ_ANY"
--description <desc>	Descripción de la clave	--description "clave CI/CD"
--overwrite	Reemplazar clave existente	--overwrite
--json	Salida legible por máquina	--json

Roles disponibles: ADMIN (acceso completo al sistema), CONNECT (funciones de Unraid Connect), VIEWER (acceso de solo lectura), GUEST (acceso limitado).

Recursos 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.

Acciones disponibles: CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN.

Opciones del comando de eliminación:

Bandera	Descripción	Ejemplo
--delete	Habilitar modo eliminación	--delete
--name <name>	Clave a eliminar (opcional)	--name "mi clave"

Si se omite --name, el comando se ejecuta de forma interactiva.

Recursos: 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

Recursos: 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

Solución de problemas

Mensajes de error comunes:

• "El nombre de la clave API debe contener solo letras, números y espacios": Elimine caracteres especiales como guiones, guiones bajos o símbolos.
• "La clave API con el nombre 'x' ya existe": Use la bandera --overwrite o elija un nombre diferente.
• "Agregue al menos un rol o permiso a la clave": Especifique --roles o --permissions (o ambos).

Para resolución de problemas, ejecute con registro de depuración:

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