Hero Supervisor Authentication

The Hero Supervisor now supports API key-based authentication with three permission scopes:

Permission Scopes

Admin - Full access to all operations including key management
Registrar - Can register new runners
User - Can create and manage jobs

Starting the Supervisor with an Admin Key

Bootstrap an initial admin key when starting the supervisor:

cargo run --bin supervisor -- --bootstrap-admin-key "my-admin"

This will output:

╔════════════════════════════════════════════════════════════╗
║  🔑 Admin API Key Created                                  ║
╚════════════════════════════════════════════════════════════╝
  Name:  my-admin
  Key:   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  Scope: admin
  ⚠️  SAVE THIS KEY - IT WILL NOT BE SHOWN AGAIN!
╚════════════════════════════════════════════════════════════╝

IMPORTANT: Save this key securely - it will not be displayed again!

API Endpoints

Verify API Key

Verify a key and get its metadata:

curl -X POST http://127.0.0.1:3030 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "auth.verify",
    "params": {
      "key": "your-api-key-here"
    },
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "valid": true,
    "name": "my-admin",
    "scope": "admin"
  },
  "id": 1
}

Create New API Key (Admin Only)

curl -X POST http://127.0.0.1:3030 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "auth.create_key",
    "params": {
      "admin_key": "your-admin-key",
      "name": "runner-bot",
      "scope": "registrar"
    },
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "key": "new-generated-uuid",
    "name": "runner-bot",
    "scope": "registrar",
    "created_at": "2025-10-27T15:00:00Z",
    "expires_at": null
  },
  "id": 1
}

List All API Keys (Admin Only)

curl -X POST http://127.0.0.1:3030 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "auth.list_keys",
    "params": {
      "admin_key": "your-admin-key"
    },
    "id": 1
  }'

Remove API Key (Admin Only)

curl -X POST http://127.0.0.1:3030 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "auth.remove_key",
    "params": {
      "admin_key": "your-admin-key",
      "key": "key-to-remove"
    },
    "id": 1
  }'

Using Keys in the Admin UI

The admin UI will use the auth.verify endpoint during login to:

Validate the provided API key
Retrieve the key's name and scope
Display the user's name and permissions in the header
Show/hide UI elements based on scope

Migration from Legacy Secrets

The supervisor still supports the legacy secret-based authentication for backward compatibility:

--admin-secret - Legacy admin secrets
--user-secret - Legacy user secrets
--register-secret - Legacy register secrets

However, the new API key system is recommended for better management and auditability.

3.4 KiB Raw Blame History