# Hero Supervisor Authentication

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

## Permission Scopes

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

## Starting the Supervisor with an Admin Key

Bootstrap an initial admin key when starting the supervisor:

```bash
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:

```bash
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:

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

### Create New API Key (Admin Only)

```bash
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:

```json
{
  "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)

```bash
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)

```bash
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:
1. Validate the provided API key
2. Retrieve the key's name and scope
3. Display the user's name and permissions in the header
4. 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.