# Authentication

## Overview

The extension supports two authentication methods:

1. **API Key** — Bearer token authentication (for llama.cpp servers and LiteLLM proxies)
2. **OAuth** — Via Pi's built-in OAuth providers (e.g., OpenRouter, Together)

## API Key Authentication

### Method 1: Interactive Login (Recommended)

1. Run `/login` in Pi
2. Select **"Use an API key"**
3. Select your provider from the list

#### Provider Selection

The login selector displays **human-readable provider names**:

- `"Local Development"` — if you configured `llamaServerName`
- `"Production LiteLLM"` — if you configured `litellmName`
- `"Llama.cpp"` — default name
- `"LiteLLM"` — default LiteLLM name

> **Tip:** You can type to filter the provider list by name. For example, type `"Lite"` to quickly find your LiteLLM provider.

#### Autocomplete

When typing `/login <tab>`, the autocomplete shows the **provider ID** (e.g., `litellm=http://localhost:4000`). This is a Pi core limitation. However, you can still:

- Type `/login Lite` to fuzzy-match by provider name
- Run `/login` without arguments to see the full interactive selector

### Method 2: Manual `auth.json` Configuration

Edit `~/.pi/agent/auth.json`:

```json
{
  "gateway-3a4b5c6d": {
    "type": "api_key",
    "key": "your-api-key"
  },
  "litellm-7e8f9a0b": {
    "type": "api_key",
    "key": "your-litellm-api-key"
  }
}
```

> **Note:** The extension also supports the legacy full-URL format for backward compatibility:
> ```json
> {
>   "llama-server=http://127.0.0.1:8080": {
>     "type": "api_key",
>     "key": "your-api-key"
>   }
> }
> ```

### Provider ID Format

Each provider has a unique ID used for authentication. The extension uses a **short hash-based ID** for cleaner display on small screens:

| Server Type | Provider ID Format | Example |
|-------------|-------------------|---------|
| Llama.cpp | `gateway-<hash>` | `gateway-3a4b5c6d` |
| LiteLLM | `litellm-<hash>` | `litellm-7e8f9a0b` |

The hash is derived from the server URL (first 8 characters of SHA-256), ensuring uniqueness while keeping the ID short. The extension also supports the legacy full-URL format (`llama-server=<url>`, `litellm=<url>`) for backward compatibility with existing `auth.json` entries.

The provider ID is **independent** of the custom server name you configure.

## OAuth Authentication

For providers with OAuth support (e.g., OpenRouter, Together), run `/login` and select **"Use a subscription"**. The extension will guide you through the OAuth flow.

## Troubleshooting

### "Unauthorized" Status

If a model shows ⛔ **Unauthorized**:

1. Run `/login` and configure your API key
2. Verify the key is correct for the target server
3. Retry loading the model

### "Failed to Load" After Auth

If loading fails after configuring auth:

1. Check the server logs for authentication errors
2. Verify the API key has the required permissions
3. Ensure the key is sent as a Bearer token (the extension handles this automatically)

### Multiple Servers with Different Keys

Each server can have its own API key. Configure them separately in `~/.pi/agent/auth.json` using their respective provider IDs.