Authentication

Three authentication methods are supported. All requests must include one of these:

API Key Authentication (Enterprise)

Create API keys from Settings → API Keys in the web UI. Use them in requests:

# Using X-API-Key header (recommended)
curl -s -H "X-API-Key: wsk_a1b2c3d4e5f6..." \
  https://your-server:8553/api/metrics

# Using Authorization: Bearer header
curl -s -H "Authorization: Bearer wsk_a1b2c3d4e5f6..." \
  https://your-server:8553/api/metrics

Session Cookie Authentication

Log in first to obtain a session cookie, then use it for subsequent requests:

# Log in and save the session cookie
curl -c cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}' \
  https://your-server:8553/api/login

# Use the cookie for API calls
curl -b cookies.txt https://your-server:8553/api/metrics

Cluster Secret Authentication

Used for inter-node communication within a cluster:

# Node-to-node request with cluster secret
curl -s -H "X-WolfStack-Secret: your-cluster-secret" \
  https://node-02:8553/api/metrics

API Key Scopes

Each API key can be restricted to specific scopes. Assign only the permissions your integration needs:

Dashboard & Metrics

# Get current system metrics
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/metrics | jq .
{
  "hostname": "node-01",
  "cpu_usage_percent": 12.5,
  "memory_total": 16777216,
  "memory_used": 7589324,
  "memory_percent": 45.2,
  "load_avg": [0.85, 1.02, 0.97],
  "uptime_seconds": 864000,
  ...
}

# Get metrics history for charts
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/metrics/history | jq '.[0]'

Cluster & Nodes

# List all nodes in the cluster
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/nodes | jq .

# Join a new node
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"address":"192.168.1.20:8553","token":"join_token_here"}' \
  https://server:8553/api/nodes

Docker Containers

# List all Docker containers
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/containers/docker | jq .

# Create a new container
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "my-nginx",
    "image": "nginx:latest",
    "ports": ["80:80","443:443"],
    "volumes": ["/data/nginx:/etc/nginx/conf.d"],
    "env": ["NGINX_HOST=example.com"],
    "restart_policy": "unless-stopped"
  }' \
  https://server:8553/api/containers/docker/create

# Stop a container
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"action":"stop"}' \
  https://server:8553/api/containers/docker/abc123def/action

LXC Containers

# List all LXC containers
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/containers/lxc | jq .

# Create a new LXC container
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "web-server",
    "template": "ubuntu",
    "release": "24.04",
    "memory_limit": "2G",
    "cpu_limit": "2"
  }' \
  https://server:8553/api/containers/lxc/create

Docker Compose

# List all Compose stacks
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/compose/stacks | jq .

# Create a new stack
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "monitoring",
    "compose": "version: \"3.8\"\nservices:\n  prometheus:\n    image: prom/prometheus\n    ports:\n      - 9090:9090"
  }' \
  https://server:8553/api/compose/stacks

# Bring a stack up
curl -X POST -H "X-API-Key: wsk_..." \
  https://server:8553/api/compose/stacks/monitoring/up

Storage & Disks

# List all storage mounts
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/storage/mounts | jq .

# Create an S3 mount
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "backup-bucket",
    "mount_type": "s3",
    "bucket": "my-backups",
    "endpoint": "https://s3.amazonaws.com",
    "access_key": "AKIA...",
    "secret_key": "...",
    "mount_point": "/mnt/s3-backups"
  }' \
  https://server:8553/api/storage/mounts

ZFS

# List ZFS pools
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/storage/zfs/pools | jq .

# Create a snapshot
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"dataset":"tank/data","snapshot_name":"daily-2026-04-04"}' \
  https://server:8553/api/storage/zfs/snapshot

Ceph

# Get Ceph cluster status
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/ceph/status | jq .

# Create a new pool
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"name":"rbd-pool","size":3,"pg_num":128}' \
  https://server:8553/api/ceph/pools

Networking

# List network interfaces
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/networking/interfaces | jq .

# Create a VLAN
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"parent":"eth0","vlan_id":100}' \
  https://server:8553/api/networking/vlans

Wake-on-LAN

Machines are stored on the node that sends their wake signal (it must be on the machine’s LAN), so every endpoint acts on that node’s machines only. Call the node directly, or reach another node through /api/nodes/{node_id}/proxy/api/wol/…. Listing and status need the read scope; adding, editing, removing and waking need a full-access (*) key when calling the node directly, or the cluster scope through the node proxy. Viewer sessions cannot change or wake machines. See Networking → Wake-on-LAN.

# Wake a machine, then wait until it answers
curl -X POST -H "X-API-Key: wsk_..." https://server:8553/api/wol/targets/{id}/wake
until curl -s -H "X-API-Key: wsk_..." https://server:8553/api/wol/status | jq -e '.["{id}"] == true' >/dev/null; do sleep 5; done

WolfNet

WolfNet is the encrypted overlay network that connects cluster nodes. Uses X25519 key exchange with ChaCha20-Poly1305 encryption.

# Check WolfNet status
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/wolfnet/status | jq .

# Add a WolfNet peer
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"public_key":"base64key...","endpoint":"203.0.113.10:51820","allowed_ip":"10.99.0.5/32"}' \
  https://server:8553/api/networking/wolfnet/peers

WireGuard Bridge

Create WireGuard VPN tunnels for remote access to cluster networks. Each cluster can have its own WireGuard interface with client configurations.

# Initialize WireGuard for a cluster
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"listen_port":51821,"address":"10.100.0.1/24"}' \
  https://server:8553/api/networking/wireguard/production/init

# Generate a client config
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"name":"laptop-paul"}' \
  https://server:8553/api/networking/wireguard/production/clients

Backups

# List all backups
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/backups | jq .

# Create a backup job
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "etc-config-backup",
    "source_paths": ["/etc/wolfstack", "/etc/nginx"],
    "target_id": "s3-backup-target",
    "retention_days": 30
  }' \
  https://server:8553/api/backups

File Manager

# Browse /etc directory
curl -s -H "X-API-Key: wsk_..." \
  "https://server:8553/api/files/browse?path=/etc" | jq .

# Read a config file
curl -s -H "X-API-Key: wsk_..." \
  "https://server:8553/api/files/read?path=/etc/hostname" | jq .

# Upload a file
curl -X POST -H "X-API-Key: wsk_..." \
  -F "file=@backup.tar.gz" -F "path=/tmp" \
  https://server:8553/api/files/upload

Security

# Get security status
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/security/status | jq .

# Add a UFW rule to allow HTTPS
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"action":"allow","port":"443","protocol":"tcp"}' \
  https://server:8553/api/security/ufw/rule

Certificates

# List certificates
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/certificates/list | jq .

# Request a new certificate
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"domain":"dashboard.example.com","email":"admin@example.com"}' \
  https://server:8553/api/certificates

Alerting

# Get alert configuration
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/alerts/config | jq .

# Update alert thresholds
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "cpu_threshold": 90,
    "memory_threshold": 85,
    "disk_threshold": 95,
    "email_recipients": ["ops@example.com"],
    "webhook_url": "https://hooks.slack.com/services/..."
  }' \
  https://server:8553/api/alerts/config

Status Pages

Uptime monitoring with public-facing status pages. All entities are cluster-scoped — pass the cluster query parameter.

# List monitors for a cluster
curl -s -H "X-API-Key: wsk_..." \
  "https://server:8553/api/statuspage/monitors?cluster=production" | jq .

# Create an HTTP monitor
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "cluster": "production",
    "name": "Main Website",
    "url": "https://example.com",
    "check_type": "http",
    "interval_seconds": 30,
    "expected_status": 200
  }' \
  https://server:8553/api/statuspage/monitors

App Store

# Browse available apps
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/appstore/apps | jq '.[0:3]'

# Prepare to install an app
curl -X POST -H "X-API-Key: wsk_..." \
  https://server:8553/api/appstore/apps/nextcloud/prepare-install | jq .

WolfRun Orchestration

Manage multi-container services across cluster nodes with automatic scaling, health checks, and rolling updates.

# List orchestrated services
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/wolfrun/services | jq .

# Scale a service to 5 replicas
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"replicas":5}' \
  https://server:8553/api/wolfrun/services/svc_abc123/scale

Kubernetes (WolfKube)

Manage lightweight Kubernetes clusters provisioned by WolfStack. Deploy apps, manage pods, and scale deployments.

# List Kubernetes clusters
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/kubernetes/clusters | jq .

# Scale a deployment
curl -X PATCH -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"replicas":3}' \
  https://server:8553/api/kubernetes/clusters/k8s_01/deployments/web-app/scale

WolfFlow Automation

Visual workflow automation engine. Create workflows with triggers, conditions, and actions to automate server management tasks.

# List all workflows
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/wolfflow/workflows | jq .

# Manually trigger a workflow
curl -X POST -H "X-API-Key: wsk_..." \
  https://server:8553/api/wolfflow/workflows/wf_abc123/run

Cron Jobs

# List all cron jobs
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/cron | jq .

# Create a cron job to run backups daily at 2 AM
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"schedule":"0 2 * * *","command":"/usr/local/bin/backup.sh","user":"root"}' \
  https://server:8553/api/cron

MySQL/MariaDB Editor

# Detect MySQL installation
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/mysql/detect | jq .

# Execute a query
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "host": "localhost",
    "user": "root",
    "password": "dbpassword",
    "database": "myapp",
    "query": "SELECT id, name FROM users LIMIT 10"
  }' \
  https://server:8553/api/mysql/query

AI Agent

Built-in AI assistant for server management. Supports Claude and Gemini models with context-aware health monitoring.

# Chat with the AI agent
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"message":"What is the current disk usage and are any disks close to full?"}' \
  https://server:8553/api/ai/chat

# Check AI agent status
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/ai/status | jq .

Secrets Manager

Encrypted key-value store for sensitive data such as API tokens, database passwords, and private keys.

# List secret keys
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/secrets | jq .

# Store a new secret
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"key":"db_password","value":"s3cur3_p@ssw0rd"}' \
  https://server:8553/api/secrets

Components & Services

Manage system components (Docker, LXC, WolfNet, etc.) and systemd services directly from the API.

# List components
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/components | jq .

# Restart the nginx service
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{"action":"restart"}' \
  https://server:8553/api/services/nginx/action

System

# Export configuration
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/config/export -o wolfstack-config.json

# Scan for issues
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/issues/scan | jq .

Enterprise API Keys

# Create a new API key
curl -X POST -H "X-API-Key: wsk_admin_key..." -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy-bot",
    "scopes": ["containers", "appstore"],
    "expires": "2027-01-01"
  }' \
  https://server:8553/api/tokens
{
  "key": { "id": "key_...", "name": "ci-deploy-bot", "scopes": ["containers","appstore"] },
  "raw_key": "wsk_a1b2c3d4e5f6...",
  "message": "Save this key now -- it will not be shown again"
}

# View audit log
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/tokens/events | jq '.[0:5]'

Nginx (WolfProxy) Configurator

Manage Nginx reverse proxy configurations. Create, edit, enable, and disable site configurations with automatic syntax validation.

# List all Nginx sites
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/configurator/nginx/sites | jq .

# Create a reverse proxy site
curl -X POST -H "X-API-Key: wsk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "app-proxy",
    "server_name": "app.example.com",
    "upstream": "http://127.0.0.1:3000",
    "ssl": true,
    "ssl_certificate": "/etc/letsencrypt/live/app.example.com/fullchain.pem",
    "ssl_certificate_key": "/etc/letsencrypt/live/app.example.com/privkey.pem"
  }' \
  https://server:8553/api/configurator/nginx/sites

# Test and reload
curl -X POST -H "X-API-Key: wsk_..." https://server:8553/api/configurator/nginx/test
curl -X POST -H "X-API-Key: wsk_..." https://server:8553/api/configurator/nginx/reload

Error Handling

All API errors return JSON with an error field and an appropriate HTTP status code:

// 400 Bad Request — invalid parameters
{ "error": "Missing required field: name" }

// 401 Unauthorized — no valid credentials
{ "error": "Invalid or expired API key" }

// 403 Forbidden — wrong scope or missing license
{ "error": "API key does not have permission for this endpoint" }
{ "error": "Enterprise license required" }

// 404 Not Found — resource does not exist
{ "error": "Container not found: abc123" }

// 409 Conflict — resource state conflict
{ "error": "Container is already running" }

// 500 Internal Server Error — unexpected failure
{ "error": "Failed to connect to Docker socket" }

Successful responses return 200 OK with a JSON body. Mutations (POST, PUT, DELETE) typically include a message field confirming the action:

{ "message": "Container started successfully" }
{ "message": "Backup schedule created", "id": "sched_abc123" }

Rate Limiting

WolfStack applies rate limiting to protect against abuse:

• Login endpoint — Maximum 10 attempts per 5 minutes per IP address. Lockouts clear automatically after the window expires.
• API endpoints — No hard rate limit on authenticated API requests. However, resource-intensive operations (backups, migrations, updates) are serialized to prevent overloading the system.
• Session lifetime — Session cookies expire after 8 hours. Expired sessions are cleaned up every 5 minutes.
• API key expiry — Enterprise API keys can have an optional expiry date. Expired keys are rejected immediately.

Installing an Enterprise License

Enterprise licenses are issued as a signed JSON file. To activate API key management:

1. Obtain your license key file from IntelligentWolf
2. Save it to /etc/wolfstack/license.key on your server
3. Restart WolfStack: sudo systemctl restart wolfstack
4. Go to Settings → API Keys to create your first key

# Save the license file
sudo tee /etc/wolfstack/license.key << 'EOF'
{
  "payload": "eyJjdXN0b21lci...",
  "signature": "dGhpcyBpcyBh..."
}
EOF

# Restart to activate
sudo systemctl restart wolfstack

# Verify the license
curl -s -H "X-API-Key: wsk_..." https://server:8553/api/platform/status | jq .