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

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 Wolf Software Systems
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 .