Programmatic API Key Management
This guide explains how to create, use, and delete API keys programmatically using the Unraid API CLI, enabling automated workflows and scripts.
Overview
The unraid-api apikey
command supports both interactive and non-interactive modes, making it suitable for:
- Automated deployment scripts
- CI/CD pipelines
- Temporary access provisioning
- Infrastructure as code workflows
Jump to the Complete Workflow Example to see everything in action.
Creating API Keys Programmatically
Basic Creation with JSON Output
Use the --json
flag to get machine-readable output:
unraid-api apikey --create --name "workflow key" --roles ADMIN --json
Output:
{
"key": "your-generated-api-key-here",
"name": "workflow key",
"id": "generated-uuid"
}
Advanced Creation with Permissions
unraid-api apikey --create \
--name "limited access key" \
--permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
--description "Read-only access for monitoring" \
--json
Handling Existing Keys
If a key with the same name exists, use --overwrite
:
unraid-api apikey --create --name "existing key" --roles ADMIN --overwrite --json
The --overwrite
flag will permanently replace the existing key. The old key will be immediately invalidated.
Deleting API Keys Programmatically
Non-Interactive Deletion
Delete a key by name without prompts:
unraid-api apikey --delete --name "workflow key"
Output:
Successfully deleted 1 API key
JSON Output for Deletion
Use --json
flag for machine-readable delete confirmation:
unraid-api apikey --delete --name "workflow key" --json
Success Output:
{
"deleted": 1,
"keys": [
{
"id": "generated-uuid",
"name": "workflow key"
}
]
}
Error Output:
{
"deleted": 0,
"error": "No API key found with name: nonexistent key"
}
Error Handling
When the specified key doesn't exist:
unraid-api apikey --delete --name "nonexistent key"
# Output: No API keys found to delete
JSON Error Output:
{
"deleted": 0,
"message": "No API keys found to delete"
}
Complete Workflow Example
Here's a complete example for temporary access provisioning:
#!/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"
Command Reference
Create Command Options
Flag | Description | Example |
---|---|---|
--name <name> | Key name (required) | --name "my key" |
--roles <roles> | Comma-separated roles | --roles ADMIN,VIEWER |
--permissions <perms> | Resource:action pairs | --permissions "DOCKER:READ_ANY" |
--description <desc> | Key description | --description "CI/CD key" |
--overwrite | Replace existing key | --overwrite |
--json | Machine-readable output | --json |
Available Roles
ADMIN
- Full system accessCONNECT
- Unraid Connect featuresVIEWER
- Read-only accessGUEST
- Limited access
Available Resources and Actions
Resources: 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
Delete Command Options
Flag | Description | Example |
---|---|---|
--delete | Enable delete mode | --delete |
--name <name> | Key to delete (optional) | --name "my key" |
Note: If --name
is omitted, the command runs interactively.
Best Practices
Minimal Permissions
- Use specific permissions instead of ADMIN role when possible
- Example:
--permissions "DOCKER:READ_ANY"
instead of--roles ADMIN
Key Lifecycle Management
- Always clean up temporary keys after use
- Store API keys securely (environment variables, secrets management)
- Use descriptive names and descriptions for audit trails
Error Handling
- Check exit codes (
$?
) after each command - Use
set -e
in bash scripts to fail fast - Implement proper cleanup with
trap
Key Naming
- Use descriptive names that include purpose and date
- Names must contain only letters, numbers, and spaces
- Unicode letters are supported
Troubleshooting
Common Issues
"API key name must contain only letters, numbers, and spaces"
- Solution: Remove special characters like hyphens, underscores, or symbols
"API key with name 'x' already exists"
- Solution: Use
--overwrite
flag or choose a different name
"Please add at least one role or permission to the key"
- Solution: Specify either
--roles
or--permissions
(or both)
Debug Mode
For troubleshooting, run with debug logging:
LOG_LEVEL=debug unraid-api apikey --create --name "debug key" --roles ADMIN