socktop-webterm/docs/src/security/token.md

# Authentication Token

This guide covers token-based authentication for securing socktop agent connections.

- **Access Control** - Only authorized clients can connect
- **Security** - Prevent unauthorized monitoring of your systems
- **Auditability** - Track which tokens are in use
- **Flexibility** - Revoke and rotate tokens as needed

## Configuring Token Authentication

### Agent Configuration

#### APT Installation

Edit `/etc/default/socktop-agent`:

```bash
sudo nano /etc/default/socktop-agent
```

Add your token:

```bash
# Authentication token
TOKEN=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8=
```

Restart the service:

```bash
sudo systemctl restart socktop-agent
```

#### Cargo Installation

Start the agent with the token:

```bash
socktop_agent --token "7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
```

Or with systemd service:

```bash
sudo systemctl edit socktop-agent
```

Add environment variable:

```ini
[Service]
Environment="TOKEN=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
```

```bash
sudo systemctl daemon-reload
sudo systemctl restart socktop-agent
```

### Client Configuration

#### Command Line

```bash
# Pass token via command line
socktop ws://server:3000 -t "7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
```

#### Connection Profile

Add token to profile (`~/.config/socktop/profiles.json`):

```json
{
  "profiles": {
    "secure-server": {
      "url": "ws://server.example.com:3000/ws?token=7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="
    }
  },
  "version": 0
}
```

Then connect:

```bash
socktop -P secure-server
```

#### Environment Variable

```bash
# Set token in environment
export SOCKTOP_TOKEN="7KJ9m3LnP4qR8sT2vW5xY6zA1bC3dE4fG7hI9jK0lM8="

# Connect without specifying token
socktop ws://server:3000
```