# API Key Management for Proxym

Proxym requires a local API key for dashboard features like Server-Sent Events (SSE) that provide real-time updates.

## Quick Start

```bash
# Initialize development environment (ensures valid local key)
make init
# or
proxym keys init

# Or just ensure a valid key exists
make key-ensure
# or
proxym keys ensure

# Generate a new local key
make key-generate
# or
proxym keys generate

# Show current key
make key-show
# or
proxym keys show
```

## What's the Issue?

When using external API keys (like OpenRouter), the dashboard's SSE connection fails because:
- SSE expects local proxym authentication
- External keys don't work with internal endpoints

## Key Types

1. **Local Keys** (format: `sk-proxy-xxxxxxxx`): 
   - Used for internal dashboard authentication
   - Required for SSE streams
   - Generated automatically by `proxym keys init` or `make init`

2. **External Keys** (e.g., `sk-or-v1-xxxxxxxx`):
   - Used for LLM providers (OpenRouter, Anthropic, etc.)
   - Set in `AI_PROXY_MASTER_KEY` for external API calls
   - NOT used for dashboard authentication

## CLI Commands

All key management is now available through the `proxym keys` command group:

- `proxym keys generate` - Generate a new local API key and update .env
- `proxym keys ensure` - Ensure a valid local key exists (generates if needed)
- `proxym keys show` - Show the current API key from .env
- `proxym keys init` - Initialize development environment with valid key

### Command Options

```bash
# Generate with custom .env file
proxym keys generate --env-file /path/to/.env

# Print key without updating .env
proxym keys generate --print-only

# Show full key (not truncated)
proxym keys show --full
```

## Makefile Shortcuts

For convenience, Makefile targets are available:

- `make init` - Initialize development environment
- `make key-generate` - Generate a new local API key  
- `make key-ensure` - Ensure a valid local API key exists
- `make key-show` - Show the current API key

## Manual Setup

If you need to set keys manually:

```bash
# Local key for dashboard (in .env)
AI_PROXY_MASTER_KEY=sk-proxy-

# Or generate a new one
proxym keys generate
```

## Troubleshooting

If you see SSE connection errors:
1. Check that your key starts with `sk-proxy-`
2. Run `make key-ensure` to fix automatically
3. Restart the proxym server after changing keys
