> ## Documentation Index
> Fetch the complete documentation index at: https://kagi.micr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth Matrix

> Complete matrix showing which commands require which authentication tokens and how fallback works.

# Authentication Matrix

This reference provides a complete mapping of which commands require which authentication tokens, including fallback behavior and special cases.

## Command Overview

| Command | Preferred Auth | Fallback | Notes |
| - | - | - | - |
| `search` (base) | Configured base-search preference | Session fallback only when API-first mode is enabled | Defaults to session unless `[auth.preferred_auth] = "api"` |
| `search --lens` | `KAGI_SESSION_TOKEN` | None | Lens requires session token |
| `search` with filters | `KAGI_SESSION_TOKEN` | None | Region, time, date, order, verbatim, and personalization filters require session token |
| `auth` | None | None | Interactive TTY wizard; writes config and validates the selected credential |
| `auth status` | None | None | Reads config only |
| `auth check` | Primary credential | None | Tests selected token |
| `auth set` | None | None | Saves credentials |
| `summarize` | `KAGI_API_TOKEN` | None | Legacy `/api/v0` public API |
| `summarize --subscriber` | `KAGI_SESSION_TOKEN` | None | Subscriber web product |
| `extract` | `KAGI_API_KEY` | None | Current `/api/v1` Extract API |
| `news` | None | None | Public endpoint |
| `quick` | `KAGI_SESSION_TOKEN` | None | Quick Answer web product |
| `ask-page` | `KAGI_SESSION_TOKEN` | None | Subscriber feature |
| `assistant` | `KAGI_SESSION_TOKEN` | None | Subscriber feature |
| `assistant custom` | `KAGI_SESSION_TOKEN` | None | Custom assistant settings |
| `lens` | `KAGI_SESSION_TOKEN` | None | Lens settings management |
| `bang custom` | `KAGI_SESSION_TOKEN` | None | Custom bang settings |
| `redirect` | `KAGI_SESSION_TOKEN` | None | Redirect rule settings |
| `translate` | `KAGI_SESSION_TOKEN` | None | Text mode only; bootstraps `translate_session` over HTTP |
| `fastgpt` | `KAGI_API_TOKEN` | None | Legacy `/api/v0` public API |
| `enrich web` | `KAGI_API_TOKEN` | None | Legacy `/api/v0` public API |
| `enrich news` | `KAGI_API_TOKEN` | None | Legacy `/api/v0` public API |
| `smallweb` | None | None | Public feed |

## Detailed Breakdown

### Search Commands

#### Base Search (`kagi search`)

```mermaid theme={null}
flowchart TD
    Start([User Query]) --> Pref{[auth.preferred_auth] = api?}

    Pref -->|No or unset| CheckSession{KAGI_SESSION_TOKEN configured?}
    CheckSession -->|Yes| TryWeb[Try web product]
    TryWeb -->|Success| ReturnResults1[Return results ✓]
    CheckSession -->|No| CheckAPI1{KAGI_API_KEY configured?}
    CheckAPI1 -->|Yes| TryAPI1[Try Search API]
    TryAPI1 -->|Success| ReturnResults2[Return results ✓]
    CheckAPI1 -->|No| Error1[Error: missing credentials]

    Pref -->|Yes| CheckAPI2{KAGI_API_KEY configured?}
    CheckAPI2 -->|Yes| TryAPI2[Try Search API]
    TryAPI2 -->|Success| ReturnResults3[Return results ✓]
    TryAPI2 -->|Auth error| CheckSession2{KAGI_SESSION_TOKEN configured?}
    CheckSession2 -->|Yes| TryWebFallback[Try web product]
    TryWebFallback -->|Success| ReturnResults4[Success ✓]
    CheckSession2 -->|No| Error2[Error: auth failed]
    CheckAPI2 -->|No| CheckSession3{KAGI_SESSION_TOKEN configured?}
    CheckSession3 -->|Yes| TryWeb2[Try web product]
    TryWeb2 -->|Success| ReturnResults5[Return results ✓]
    CheckSession3 -->|No| Error3[Error: missing credentials]
```

**Key insight:** Base search is the only command with fallback behavior, and that fallback only matters when you explicitly opt into API-first mode.

#### Lens Search (`kagi search --lens <INDEX>`)

```mermaid theme={null}
flowchart TD
    Start([User Query with --lens]) --> CheckSession{KAGI_SESSION_TOKEN configured?}
    
    CheckSession -->|Yes| QueryWeb[Query web product with lens]
    QueryWeb -->|Success| ReturnResults[Success ✓]
    
    CheckSession -->|No| Error[Error: missing credentials]
```

**No fallback:** Lens search requires session token exclusively.

#### Search Filters and Session-Only Options

```mermaid theme={null}
flowchart TD
    Start([User Query with Search Options]) --> ApiCompat{Only region/date filters?}
    ApiCompat -->|Yes| AuthPref{API path selected or no session token?}
    AuthPref -->|Yes| QueryApi[Query /api/v1/search with filters]
    AuthPref -->|No| QueryWeb[Query web product with filters]

    ApiCompat -->|No| CheckSession{KAGI_SESSION_TOKEN configured?}
    CheckSession -->|Yes| QueryWeb

    QueryApi -->|Success| ReturnResults[Success ✓]
    QueryWeb -->|Success| ReturnResults
    CheckSession -->|No| Error[Error: missing session token]
```

`--region`, `--from-date`, and `--to-date` map to the current V1 Search API `filters` object. `--lens`, `--time`, `--order`, `--verbatim`, and personalization flags remain session-only because they target the subscriber web-product flow exposed by this CLI.

### Authentication Commands

#### `kagi auth`

* **Purpose:** Interactive setup wizard
* **Network:** Yes, during credential validation
* **Uses:** The credential the user just pasted
* **Writes:** `~/.config/kagi-cli/config.toml`
* **TTY only:** In non-interactive environments, use `auth set`, `status`, or `check`

#### `kagi auth status`

* **Purpose:** Display current configuration
* **Network:** No
* **Reads:** Environment variables, config file
* **Output:** Shows which tokens are configured and their sources

#### `kagi auth check`

* **Purpose:** Validate credentials work
* **Network:** Yes (test search)
* **Uses:** Primary credential per `[auth.preferred_auth]` setting (defaults to session token)
* **No fallback:** Tests primary credential only

#### `kagi auth set`

* **Purpose:** Save credentials to file
* **Network:** No
* **Writes:** `~/.config/kagi-cli/config.toml`
* **Creates:** Config file if doesn't exist

### Content Commands

#### Summarization

| Mode | Token | Notes |
| - | - | - |
| Public API (default) | `KAGI_API_TOKEN` | Uses legacy Universal Summarizer API |
| Subscriber (`--subscriber`) | `KAGI_SESSION_TOKEN` | Uses web product summarizer |

**Important:** These are mutually exclusive. You cannot use `--subscriber` with API-only options like `--engine`.

#### AI Commands

| Command | Token | Purpose |
| - | - | - |
| `quick` | `KAGI_SESSION_TOKEN` | Quick answers with references |
| `ask-page` | `KAGI_SESSION_TOKEN` | Ask Assistant about one page URL |
| `assistant` | `KAGI_SESSION_TOKEN` | Conversational AI with threads |
| `assistant custom` | `KAGI_SESSION_TOKEN` | Create and manage saved assistants |
| `translate` | `KAGI_SESSION_TOKEN` | Kagi Translate text mode |
| `fastgpt` | `KAGI_API_TOKEN` | Quick factual answers through legacy `/api/v0` |
| `extract` | `KAGI_API_KEY` | Full-page markdown extraction through current `/api/v1` |

#### Settings Commands

| Command | Token | Purpose |
| - | - | - |
| `lens` | `KAGI_SESSION_TOKEN` | Manage search lenses |
| `bang custom` | `KAGI_SESSION_TOKEN` | Manage custom bangs |
| `redirect` | `KAGI_SESSION_TOKEN` | Manage redirect rules |

### Data Commands

#### Enrichment

Both `enrich web` and `enrich news` require legacy `KAGI_API_TOKEN`:

* **Teclis** (web) - Enhanced web search
* **TinyGem** (news) - Enhanced news search

### Feed Commands

#### Public Feeds (No Auth Required)

| Command | Endpoint | Update Frequency |
| - | - | - |
| `news` | Kagi News | Continuous |
| `smallweb` | Small Web | Periodic |

## Token Requirements by Feature

### Session Token Features

Requires `KAGI_SESSION_TOKEN`:

* ✅ Lens-aware search (`--lens`)
* ✅ Quick Answer (`quick`)
* ✅ Session-only search options (`--lens`, `--time`, `--order`, `--verbatim`, personalization flags)
* ✅ Kagi Assistant prompt and thread commands (`assistant`)
* ✅ Custom assistant management (`assistant custom`)
* ✅ Ask Page (`ask-page`)
* ✅ Lens management (`lens`)
* ✅ Custom bang management (`bang custom`)
* ✅ Redirect management (`redirect`)
* ✅ Kagi Translate (`translate`)
* ✅ Subscriber Summarizer (`summarize --subscriber`)
* ✅ Base search (fallback)

### API Key Features

Requires `KAGI_API_KEY`:

* ✅ Current Search API (`search` when `[auth.preferred_auth] = "api"`)
* ✅ Extract API (`extract`)

### Legacy API Token Features

Requires `KAGI_API_TOKEN`:

* ✅ FastGPT (`fastgpt`)
* ✅ Public Summarizer (`summarize`)
* ✅ Web Enrichment (`enrich web`)
* ✅ News Enrichment (`enrich news`)

### No Token Required

Works without authentication:

* ✅ Kagi News (`news`)
* ✅ Small Web (`smallweb`)
* ✅ Auth status (`auth status`)

## Configuration Precedence

### Resolution Order

```
1. Environment Variables (KAGI_API_KEY, KAGI_API_TOKEN, KAGI_SESSION_TOKEN)
   ↓ (if not set)
2. Configuration File (`~/.config/kagi-cli/config.toml`)
   ↓ (if not set)
3. Missing (error for commands requiring auth)
```

The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`. Environment variables override the config file.

### Example Scenarios

**Scenario 1: Multiple credentials in file**

```toml theme={null}
# ~/.config/kagi-cli/config.toml
[auth]
api_token = "api123"
api_key = "key123"
session_token = "session456"
```

* `search`: Uses the configured base-search preference (session by default)
* `assistant`: Uses session token
* `assistant custom`: Uses session token
* `lens`: Uses session token
* `news`: No token needed

**Scenario 2: Mixed sources**

```bash theme={null}
export KAGI_API_KEY="key789"
# ~/.config/kagi-cli/config.toml has session_token only
```

* `search`: Uses env API key when `[auth.preferred_auth] = "api"`
* `summarize --subscriber`: Uses file session token
* `fastgpt`: Requires `KAGI_API_TOKEN` or `[auth].api_token`

**Scenario 3: Environment overrides file**

```bash theme={null}
export KAGI_SESSION_TOKEN="special_session"
# ~/.config/kagi-cli/config.toml has different session_token
```

* `search`: Uses env session token (not API, so tries web)
* `assistant`: Uses env session token
* `redirect`: Uses env session token

## Common Configurations

### Session Token Only

**Setup:**

```bash theme={null}
kagi auth set --session-token 'https://kagi.com/search?token=...'
```

**Working commands:**

* ✅ `kagi search "query"` (uses session path)
* ✅ `kagi search --lens 2 "query"`
* ✅ `kagi quick "what is rust"`
* ✅ `kagi search --region us --time month "query"`
* ✅ `kagi ask-page https://example.com "question"`
* ✅ `kagi assistant "prompt"`
* ✅ `kagi assistant custom list`
* ✅ `kagi lens list`
* ✅ `kagi bang custom list`
* ✅ `kagi redirect list`
* ✅ `kagi translate "Bonjour tout le monde"`
* ✅ `kagi summarize --subscriber --url ...`
* ✅ `kagi news`
* ✅ `kagi smallweb`

**Non-working:**

* ❌ `kagi fastgpt` - requires API token
* ❌ `kagi summarize --url ...` (without --subscriber) - requires API token
* ❌ `kagi enrich web` - requires API token
* ❌ `kagi extract` - requires API key

### Legacy API Token Only

**Setup:**

```bash theme={null}
kagi auth set --api-token 'your_api_token'
```

**Working commands:**

* ✅ `kagi summarize --url ...`
* ✅ `kagi fastgpt "query"`
* ✅ `kagi enrich web "query"`
* ✅ `kagi news`
* ✅ `kagi smallweb`

**Non-working:**

* ❌ `kagi search "query"` with `[auth.preferred_auth] = "api"` - requires API key or session token
* ❌ `kagi search --lens 2` - requires session token
* ❌ `kagi quick` - requires session token
* ❌ `kagi search --region us "query"` - requires session token
* ❌ `kagi ask-page https://example.com "question"` - requires session token
* ❌ `kagi quick` - requires session token
* ❌ `kagi assistant` - requires session token
* ❌ `kagi assistant custom list` - requires session token
* ❌ `kagi lens list` - requires session token
* ❌ `kagi bang custom list` - requires session token
* ❌ `kagi redirect list` - requires session token
* ❌ `kagi summarize --subscriber` - requires session token
* ❌ `kagi extract` - requires API key

### Session Token, API Key, and Legacy API Token

**Setup:**

```bash theme={null}
kagi auth set --session-token '...' --api-key '...' --api-token '...'
```

**All commands work:**

* ✅ Everything listed above

**Smart behavior:**

* `search`: Uses session (default), or API key if `[auth.preferred_auth = "api"]` is set
* `extract`: Uses API key directly
* `summarize` without `--subscriber`: Uses legacy API token
* `summarize --subscriber`: Uses session
* `quick`: Uses session
* `ask-page`: Uses session
* `assistant`: Uses session
* `assistant custom`: Uses session
* `lens`: Uses session
* `bang custom`: Uses session
* `redirect`: Uses session
* `fastgpt`: Uses legacy API token

## Troubleshooting Matrix

| Symptom | Check | Solution |
| - | - | - |
| "missing credentials" | `kagi auth status` | Set appropriate token |
| "requires KAGI\_SESSION\_TOKEN" | Token type | Use `--subscriber` or set session token |
| "requires KAGI\_API\_KEY" | Token type | Set API key for current Search API or Extract |
| "requires KAGI\_API\_TOKEN" | Token type | Remove `--subscriber` or set legacy API token |
| "auth check failed" | Token validity | Regenerate token in Kagi settings |
| `search --lens` fails | Session token | Verify session token configured |
| `fastgpt` fails | Legacy API token + credit | Check API credit balance |

## Security Considerations

### Token Storage

* **Environment variables:** Process-wide, may leak to subprocesses
* **Config file:** Stored on disk, should be 600 permissions
* **Shell history:** May contain `export` commands

**Recommendation:** Use config file for persistence, environment variables for overrides.

### Scope of Access

* **Session Token:** Full subscriber access (search, assistant, summarizer)
* **API Key:** Current `/api/v1` API-only access (search, extract)
* **Legacy API Token:** Older `/api/v0` API-only access (fastgpt, enrich, public summarizer)

**Principle:** Use least-privilege tokens for specific workflows.

## Migration Scenarios

### Adding API to existing Session setup

```bash theme={null}
# Already have session token
kagi auth set --api-token 'new_api_token'

# Now fastgpt works
kagi fastgpt "question"
```

### Adding Session to existing API setup

```bash theme={null}
# Already have API token
kagi auth set --session-token 'https://kagi.com/search?token=...'

# Now assistant works
kagi assistant "prompt"
```

## Reference Tables

### Quick Reference

| Want to... | Token Needed | Command |
| - | - | - |
| Search generally | Either | `kagi search` |
| Use my lens | Session | `kagi search --lens` |
| Manage my lenses | Session | `kagi lens` |
| Quick answer from the web product | Session | `kagi quick` |
| Faster factual answer from the API | API | `kagi fastgpt` |
| AI conversation | Session | `kagi assistant` |
| Manage saved assistants | Session | `kagi assistant custom` |
| Manage custom bangs | Session | `kagi bang custom` |
| Manage redirect rules | Session | `kagi redirect` |
| Translate text | Session | `kagi translate` |
| Summarize (free API) | API | `kagi summarize --url` |
| Summarize (subscription) | Session | `kagi summarize --subscriber` |
| Read news | None | `kagi news` |
| Explore small web | None | `kagi smallweb` |

### Error to Action Mapping

| Error | Meaning | Action |
| - | - | - |
| `requires KAGI_API_TOKEN` | Need API access | Set API token or check command flags |
| `requires KAGI_SESSION_TOKEN` | Need subscriber access | Set session token |
| `missing credentials` | No token configured | Set appropriate token |
| `auth check failed` | Token invalid | Regenerate token |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.