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:

• Scripts de despliegue automatizado
• Canales de CI/CD
• Provisión de acceso temporal
• Flujos de trabajo de infraestructura como código

Quick Iniciar

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

Creación Programática de Claves API

Creación Básica con Salida en JSON

Use la bandera --json para obtener una salida legible por máquina:

unraid-api apikey --create --name "clave de flujo de trabajo" --roles ADMIN --json

Salida:

{
 "key": "tu-clave-api-generada-aquí",
 "name": "clave de flujo de trabajo",
 "id": "uuid-generado"
}

Creación Avanzada con Permisos

unraid-api apikey --create \
 --name "clave de acceso limitado" \
 --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
 --description "Acceso de solo lectura para monitoreo" \
 --json

Gestión de Claves Existentes

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

unraid-api apikey --create --name "clave existente" --roles ADMIN --overwrite --json

Key Reemplazo

El modificador --overwrite reemplazará permanentemente la clave existente. La clave antigua será invalidada inmediatamente.

Eliminación Programática de Claves API

Eliminación No Interactiva

Eliminar una clave por nombre sin confirmaciones:

unraid-api apikey --delete --name "clave de flujo de trabajo"

Salida:

1 Clave API eliminada exitosamente

Salida en JSON para Eliminación

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

unraid-api apikey --delete --name "clave de flujo de trabajo" --json

Salida de Éxito:

{
 "deleted": 1,
 "keys": [
 {
 "id": "uuid-generado",
 "name": "clave de flujo de trabajo"
 }
 ]
}

Salida de Error:

{
 "deleted": 0,
 "error": "No se encontró ninguna clave API con el nombre: clave inexistente"
}

Gestión de Errores

Cuando la clave especificada no existe:

unraid-api apikey --delete --name "clave inexistente"
# Salida: No se encontraron claves API para eliminar

Salida de Error en JSON:

{
 "deleted": 0,
 "message": "No se encontraron claves API para eliminar"
}

Ejemplo Completo de Flujo de Trabajo

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

#!/bin/bash
set -e

# 1. Crear clave API temporal
echo "Creando clave API temporal..."
KEY_DATA=$(unraid-api apikey --create \
 --name "clave de despliegue temporal" \
 --roles ADMIN \
 --description "Clave temporal para despliegue $(date)" \
 --json)

# 2. Extraer la clave API
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "Clave API creada exitosamente"

# 3. Usar la clave para operaciones
echo "Configurando servicios..."
curl -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"provider": "azure", "clientId": "your-client-id"}' \
 http://localhost:3001/graphql

# 4. Limpieza (siempre se ejecuta, incluso en error)
trap 'echo "Limpiando..."; unraid-api apikey --delete --name "clave de despliegue temporal"' EXIT

echo "Despliegue completado exitosamente"

Referencia de Comandos

Opciones del Comando de Creación

Modificador	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 total al sistema
• CONNECT - Funciones de Unraid Connect
• VIEWER - Acceso de solo lectura
• GUEST - Acceso limitado

Recursos y Acciones Disponibles

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

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

Opciones del Comando de Eliminación

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

Nota: Si se omite --name, el comando se ejecuta de manera interactiva.

Mejores Prácticas

Security Mejores Prácticas

Permisos Mínimos

• Usar permisos específicos en lugar del rol ADMIN cuando sea posible
• Ejemplo: --permissions "DOCKER:READ_ANY" en lugar de --roles ADMIN

Gestión del Ciclo de Vida de las Claves

• Siempre limpiar claves temporales después de su uso
• Almacenar claves API de forma segura (variables de entorno, gestión de secretos)
• Utilizar nombres y descripciones descriptivos para el rastro de auditoría

Gestión de Errores

• Verificar códigos de salida ($?) después de cada comando
• Usar set -e en scripts bash para fallar rápidamente
• Implementar limpieza adecuada con trap

Nomenclatura de Claves

• Usar nombres descriptivos que incluyan propósito y fecha
• Los nombres deben contener solo letras, números y espacios
• Se admiten letras Unicode

Solución de problemas

Problemas Comunes

Common Mensajes de Error

"El nombre de la clave API debe contener solo letras, números y espacios"

• Solución: Elimine caracteres especiales como guiones, guiones bajos o símbolos

"Una clave API con el nombre 'x' ya existe"

• Solución: Use la bandera --overwrite o elija un nombre diferente

"Por favor, añada al menos un rol o permiso a la clave"

• Solución: Especifique ya sea --roles o --permissions (o ambos)

Modo de Depuración

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

LOG_LEVEL=debug unraid-api apikey --create --name "clave de depuración" --roles ADMIN