Skip to content
LabTether

API Key Management

Key Format

API keys use the format lt_<prefix>_<secret>:

  • lt_ — identifies it as a LabTether API key
  • <prefix> — 4-character identifier (visible in key listings)
  • <secret> — 32 bytes of cryptographic randomness, base32 encoded

Example: lt_a1b2_x8k9m2p4q7r3s5t2u6v9w4y7z8a2b5c3d6e9f

Creating Keys

curl -X POST https://hub:8443/api/v2/keys \
  -H "Authorization: Bearer $OWNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openclaw-homelab",
    "role": "operator",
    "scopes": ["assets:read", "assets:exec", "docker:read"],
    "allowed_assets": ["server1", "server2"],
    "expires_at": "2026-06-01T00:00:00Z"
  }'

The response includes raw_key — save it immediately, it's never shown again.

Key Properties

Field Description
name Human-readable label (max 120 chars)
role Permission level: owner, admin, operator, viewer
scopes Fine-grained permissions (see Scope Reference below)
allowed_assets Optional asset ID allowlist (empty = all assets)
expires_at Optional expiry timestamp (ISO 8601)

Scope Reference

Scope Covers
assets:read List and get asset details
assets:write Add, update, remove assets
assets:exec Run commands on assets
assets:power Reboot, shutdown, wake
files:read List, download files
files:write Upload, create, delete, rename files
files:* All file operations
services:read List services
services:write Start, stop, restart services
services:* All service operations
processes:read List processes
processes:kill Kill processes
docker:read List containers, images, volumes, logs
docker:write Start, stop, manage containers, deploy stacks
docker:* All Docker operations
connectors:read Query Proxmox, TrueNAS, PBS, Portainer
connectors:write Manage VMs, storage, etc.
groups:read List groups
groups:write Manage groups
alerts:read View alerts and incidents
alerts:write Acknowledge, silence alerts
metrics:read Query metrics
homeassistant:read View HA entities
homeassistant:write Control HA devices
agents:read View agent status
agents:write Manage agents
webhooks:* Manage webhooks
schedules:* Manage scheduled tasks
actions:* Manage saved actions
hub:read Hub status
* Everything (use sparingly)

Managing Keys

# List all keys
curl https://hub:8443/api/v2/keys -H "Authorization: Bearer $OWNER_TOKEN"

# Get key details
curl https://hub:8443/api/v2/keys/key_id -H "Authorization: Bearer $OWNER_TOKEN"

# Update scopes
curl -X PATCH https://hub:8443/api/v2/keys/key_id \
  -H "Authorization: Bearer $OWNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["assets:read", "assets:exec", "docker:*"]}'

# Revoke a key
curl -X DELETE https://hub:8443/api/v2/keys/key_id \
  -H "Authorization: Bearer $OWNER_TOKEN"

Security Properties

  • SHA-256 hashed — raw key is never stored, only the hash
  • TLS required — keys are rejected on plain HTTP connections
  • Per-key rate limiting — 600 req/min per source IP, 3000 req/min global
  • Constant-time comparison — prevents timing attacks
  • Audit logged — key creation and deletion events recorded
  • Expiry — keys can have optional expiry dates