IRC-kosmi-relay/docs/setup/QUICK_START_AUTH.md

# Quick Start: Authenticated Kosmi Access

## Step 1: Create Bot Account

1. Go to https://app.kosmi.io
2. Sign up with a dedicated email (e.g., `your-bot@example.com`)
3. Choose a display name (e.g., "HSO Relay Bot")
4. Save the credentials securely

## Step 2: Configure Matterbridge

Edit `matterbridge.toml`:

```toml
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@yourroom"
Email="your-bot@example.com"
Password="your-secure-password"
```

## Step 3: Run and Verify

```bash
./matterbridge -conf matterbridge.toml
```

Watch the logs for:
- `"Authenticating with email/password..."` -- browser login starting
- `"✅ Authentication successful"` -- login completed
- `"💾 Token cached"` -- token saved for reuse
- `"Successfully connected to Kosmi"` -- connected to room

On subsequent runs with a cached token:
- `"✅ Using cached token"` -- no browser needed

## Step 4: Test

1. Send a message in the Kosmi room from a browser
2. Verify it appears in your IRC channel
3. Send a message from IRC
4. Verify it appears in Kosmi with the bot's display name

## Verification Checklist

- [ ] Bot account created at app.kosmi.io
- [ ] Credentials added to `matterbridge.toml`
- [ ] Bridge logs show authenticated connection
- [ ] Bot display name appears correctly in chat
- [ ] Messages relay bidirectionally
- [ ] Token cache file exists (`data/kosmi_token_cache.json` or `~/.matterbridge/kosmi_token_cache.json`)

## Troubleshooting

### Anonymous connection despite credentials

Check that both `Email` and `Password` are set and non-empty:
```bash
grep -E "Email|Password" matterbridge.toml
```

### Authentication fails

- Verify Chrome/Chromium is installed
- Test credentials by logging in manually at app.kosmi.io
- Delete cached token to force fresh auth: `rm data/kosmi_token_cache.json`
- Enable debug logging: `-debug`

### Token expired

The bridge automatically refreshes tokens expiring within 7 days. If refresh fails:
- Check logs for authentication errors
- Verify credentials are still valid
- Delete the token cache and restart

## Next Steps

- See [BROWSER_AUTH_GUIDE.md](BROWSER_AUTH_GUIDE.md) for full authentication details
- See [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md) for token caching behavior