Merge pull request #112 from Microck/feat/api-key-token-split

feat(auth)!: split API keys from legacy tokens

Author: Microck

.env.example

@@ -1,4 +1,7 @@
-# Preferred for base search when your account has Search API access.
+# Current Kagi API key for /api/v1 endpoints such as Search API and Extract.
+KAGI_API_KEY=
+
+# Legacy Kagi API token for /api/v0 endpoints such as FastGPT, Summarizer, and Enrich.
 KAGI_API_TOKEN=
 
 # Required for lens-aware search and the proven HTML/session path.

CHANGELOG.md

@@ -7,11 +7,20 @@ Before `1.0.0`, breaking changes may still ship in minor releases.
 
 ## [Unreleased]
 
+### Added
+
+- Added `KAGI_API_KEY`, `[auth].api_key`, and `kagi auth set --api-key` for current `/api/v1` Search and Extract API credentials.
+
+### Changed
+
+- Breaking: split current API keys from legacy API tokens. `KAGI_API_TOKEN` and `[auth].api_token` now represent legacy `/api/v0` credentials only, while base Search API mode requires `KAGI_API_KEY` or `[auth].api_key`.
+
 ## [0.6.2]
 
 ### Added
 
 - Added `kagi_extract` to the built-in MCP server tool list, matching the existing paid Extract API command behavior.
+- `kagi extract` and MCP `kagi_extract` now reject session-only Extract on Kagi accounts whose API portal disallows Extract API access, avoiding legacy token regeneration loops.
 
 ## [0.6.1]
 

README.md

@@ -18,7 +18,7 @@
 
 `kagi` is a terminal CLI for Kagi that gives you command-line access to search, quick answers, ask-page, assistant, translate, summarization, public feeds through `news` and `smallweb`, paid API commands like `fastgpt` and `enrich`, and account-level settings like lenses, custom assistants, custom bangs, and redirect rules. it is built for people who want one command surface for interactive use, shell workflows, and structured JSON output.
 
-the main setup path is `kagi auth`. on a real terminal it opens a guided setup flow where you choose `Session Link` or `API Token`, get the official instructions inline, paste the credential, save it to `./.kagi.toml`, and validate it immediately. if you also use Kagi's paid API, the same wizard can add that too.
+the main setup path is `kagi auth`. on a real terminal it opens a guided setup flow where you choose `Session Link`, `API Key`, or `Legacy API Token`, get the official instructions inline, paste the credential, save it to `./.kagi.toml`, and validate it immediately. if you also use Kagi's paid API, the same wizard can add that too.
 
 [documentation](https://kagi.micr.dev) | [npm](https://www.npmjs.com/package/kagi-cli) | [mcp](https://github.com/Microck/kagi-mcp)
 
@@ -31,7 +31,7 @@ if you already use Kagi and want to access it from scripts, shell workflows, or
 - use your existing session-link URL for subscriber features
 - get structured JSON for scripts, agents, and other tooling
 - use one CLI for search, quick answers, assistant, translate, summarization, `news`, and `smallweb`
-- add `KAGI_API_TOKEN` only when you want the paid public API commands
+- add `KAGI_API_KEY` for current `/api/v1` commands, or `KAGI_API_TOKEN` for legacy `/api/v0` commands
 
 ## quickstart
 
@@ -79,7 +79,8 @@ kagi auth
 the wizard is the default setup path. it guides you through:
 
 - `Session Link` from `https://kagi.com/settings/user_details`
-- `API Token` from `https://kagi.com/settings/api`
+- `API Key` from `https://kagi.com/api/keys`
+- `Legacy API Token` from `https://kagi.com/settings/api`
 - saving into `./.kagi.toml`
 - immediate validation
 
@@ -101,29 +102,29 @@ kagi auth set --session-token 'https://kagi.com/search?token=...'
 kagi auth check
 ```
 
-add an api token when you want the paid public api commands:
+add an api key when you want current paid api commands:
 
 
 how to get it:
 
 1. click the top-right menu icon
 2. go into `Settings`
-3. click `Advanced` in the left sidebar
-4. go into `Open API Portal`
-5. under `API Token`, click `Generate New Token`
+3. open `https://kagi.com/api/keys`
+4. generate or copy an API key
 
 ![api token tutorial](images/tutorials/api-token.gif)
 
 ```bash
-export KAGI_API_TOKEN='...'
+export KAGI_API_KEY='...'
 ```
 
 ## auth model
 
 | credential | what it unlocks |
 | --- | --- |
-| `KAGI_SESSION_TOKEN` | base search fallback, `search --lens`, filtered search, `quick`, `ask-page`, `assistant`, `translate`, `summarize --subscriber` |
-| `KAGI_API_TOKEN` | public `summarize`, `extract`, `fastgpt`, `enrich web`, `enrich news` |
+| `KAGI_SESSION_TOKEN` | base search fallback, `search --lens`, filtered search, `quick`, `ask-page`, `assistant`, `translate`, `summarize --subscriber`, and Extract eligibility checks through the authenticated API portal |
+| `KAGI_API_KEY` | current `/api/v1` Search API and Extract API with `Bearer` auth |
+| `KAGI_API_TOKEN` | legacy `/api/v0` public `summarize`, `fastgpt`, `enrich web`, and `enrich news` with `Bot` auth |
 | none | `news`, `smallweb`, `auth status`, `--help` |
 
 example config:
@@ -133,15 +134,19 @@ example config:
 # Full Kagi session-link URL or just the raw token value.
 session_token = "https://kagi.com/search?token=kagi_session_demo_1234567890abcdef"
 
-# Paid API token for summarize, fastgpt, and enrich commands.
-api_token = "kagi_api_demo_abcdef1234567890"
+# Current API key for Search API and Extract.
+api_key = "kagi_api_key_demo_abcdef1234567890"
+
+# Legacy API token for summarize, fastgpt, and enrich commands.
+api_token = "kagi_api_token_demo_abcdef1234567890"
 
 # Base `kagi search` auth preference: "session" or "api".
 preferred_auth = "api"
 
 [profiles.work.auth]
 session_token = "https://kagi.com/search?token=work_session_demo"
-api_token = "kagi_api_work_demo"
+api_key = "kagi_api_key_work_demo"
+api_token = "kagi_api_token_work_demo"
 preferred_auth = "session"
 ```
 notes:
@@ -165,7 +170,7 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 | `kagi batch` | run multiple searches in parallel with JSON, TOON, compact, pretty, markdown, or csv output and shared filters |
 | `kagi auth` | launch the auth wizard, or inspect, validate, and save credentials |
 | `kagi summarize` | use the paid public summarizer API or the subscriber summarizer with `--subscriber` |
-| `kagi extract` | extract a page's full content as markdown through the paid API |
+| `kagi extract` | extract a page's full content as markdown through the current paid API, using `KAGI_API_KEY` directly; session-only auth is rejected when Kagi's API portal does not allow Extract access |
 | `kagi watch` | rerun a search on an interval and emit added/removed result URLs |
 | `kagi notify` | send search or news output to a webhook |
 | `kagi history` | inspect local command history and aggregate query stats |

docs/SKILL.md

@@ -47,7 +47,7 @@ kagi auth
 ```
 
 Opens a guided TTY wizard that walks through:
-- Choosing Session Link (subscriber, free) or API Token (paid)
+- Choosing Session Link, API Key, or Legacy API Token
 - Pasting credentials
 - Saving to `./.kagi.toml`
 - Immediate validation
@@ -61,7 +61,10 @@ kagi auth set --session-token 'https://kagi.com/search?token=...'
 # Or via environment variable
 export KAGI_SESSION_TOKEN='...'
 
-# API token (from https://kagi.com/settings/api)
+# API key for current /api/v1 endpoints (from https://kagi.com/api/keys)
+export KAGI_API_KEY='...'
+
+# Legacy API token for /api/v0 endpoints (from https://kagi.com/settings/api)
 export KAGI_API_TOKEN='...'
 ```
 
@@ -70,10 +73,11 @@ export KAGI_API_TOKEN='...'
 | Credential | What It Unlocks |
 |------------|-----------------|
 | `KAGI_SESSION_TOKEN` | base search fallback, `search --lens`, `search --news`, filtered search, `quick`, `ask-page`, `assistant`, `translate`, `summarize --subscriber` |
+| `KAGI_API_KEY` | search API, extract |
 | `KAGI_API_TOKEN` | summarize, fastgpt, enrich web, enrich news |
 | none | news, smallweb, auth status, --help |
 
-Environment variables override `./.kagi.toml`. When both tokens are present, base `kagi search` defaults to session token; set `[auth] preferred_auth = "api"` in config to prefer API.
+Environment variables override `./.kagi.toml`. When a session token and API key are both present, base `kagi search` defaults to the session token; set `[auth] preferred_auth = "api"` in config to prefer the API key.
 
 ## Commands
 

docs/commands/auth.mdx

@@ -5,7 +5,7 @@ description: "Reference for the kagi auth wizard and non-interactive credential
 
 # `kagi auth`
 
-`kagi auth` is the main onboarding path for this CLI. On a real terminal, it launches an interactive setup wizard that lets you choose `Session Link` or `API Token`, shows the official Kagi settings page for that credential, accepts a paste, saves into `./.kagi.toml`, and validates the selected credential immediately.
+`kagi auth` is the main onboarding path for this CLI. On a real terminal, it launches an interactive setup wizard that lets you choose `Session Link`, `API Key`, or `Legacy API Token`, shows the official Kagi settings page for that credential, accepts a paste, saves into `./.kagi.toml`, and validates the selected credential immediately.
 
 ![Auth command demo](/images/demos/auth.gif)
 
@@ -29,7 +29,7 @@ kagi auth
 The wizard flow is:
 
 1. shows your current auth state and config path
-2. lets you choose `Session Link` or `API Token`
+2. lets you choose `Session Link`, `API Key`, or `Legacy API Token`
 3. shows the official place to get that credential
 4. accepts the pasted value
 5. asks before overwriting an existing config value of the same type
@@ -50,7 +50,19 @@ It accepts either:
 - the full Session Link URL
 - the raw token value
 
-### API Token Path
+### API Key Path
+
+The wizard points you to:
+
+```text
+https://kagi.com/api/keys
+```
+
+It accepts:
+
+- the raw API key
+
+### Legacy API Token Path
 
 The wizard points you to:
 
@@ -60,7 +72,7 @@ https://kagi.com/settings/api
 
 It accepts:
 
-- the raw API token
+- the raw legacy API token
 
 ### Non-TTY Behavior
 
@@ -94,7 +106,8 @@ Example:
 selected: session-token (config)
 profile: default
 preferred auth for base search: session
-api token: not configured
+api key: not configured
+legacy api token: not configured
 session token: configured via config
 config path: .kagi.toml
 precedence: env > selected profile config > default config; base search defaults to session unless preferred_auth = "api"; lens search requires session token
@@ -118,21 +131,27 @@ auth check passed: session-token (config)
 auth check passed: api-token (env)
 ```
 
+```text
+auth check passed: api-key (env)
+```
+
 ## `kagi auth set`
 
 Use this when you want scripting or explicit non-interactive config writes.
 
 ```bash
 kagi auth set --session-token 'https://kagi.com/search?token=...'
+kagi auth set --api-key '...'
 kagi auth set --api-token '...'
-kagi auth set --session-token 'https://kagi.com/search?token=...' --api-token '...'
+kagi auth set --session-token 'https://kagi.com/search?token=...' --api-key '...' --api-token '...'
 kagi --profile work auth set --session-token 'https://kagi.com/search?token=...'
 ```
 
 Options:
 
 - `--session-token <TOKEN_OR_URL>` saves a Session Link or raw session token
-- `--api-token <TOKEN>` saves a raw API token
+- `--api-key <KEY>` saves a current API key for `/api/v1` endpoints
+- `--api-token <TOKEN>` saves a legacy API token for `/api/v0` endpoints
 
 Behavior:
 
@@ -145,7 +164,7 @@ Behavior:
 
 The CLI resolves credentials in this order:
 
-1. `KAGI_API_TOKEN` / `KAGI_SESSION_TOKEN`
+1. `KAGI_API_KEY` / `KAGI_API_TOKEN` / `KAGI_SESSION_TOKEN`
 2. selected profile config, such as `[profiles.work.auth]`
 3. default `./.kagi.toml` `[auth]`
 
@@ -154,7 +173,8 @@ Environment variables override the config file. Use `--profile <NAME>` to select
 ```toml
 [profiles.work.auth]
 session_token = "work-session"
-api_token = "work-api"
+api_key = "work-api-key"
+api_token = "work-legacy-api-token"
 preferred_auth = "session"
 ```
 
@@ -184,17 +204,17 @@ kagi auth set --session-token 'https://kagi.com/search?token=...'
 kagi auth check
 ```
 
-### Add API Token Later
+### Add API Credentials Later
 
 ```bash
 kagi auth
 ```
 
-Choose `API Token`, paste it, then verify:
+Choose `API Key` for current Search API or Extract access. Choose `Legacy API Token` for FastGPT, public Summarizer, or Enrich.
 
 ```bash
 kagi auth status
-kagi fastgpt "what changed in rust 1.86?"
+kagi search --format pretty "what changed in rust 1.86?"
 ```
 
 ## Security Notes

docs/commands/enrich.mdx

@@ -26,7 +26,7 @@ These endpoints provide enhanced search capabilities beyond standard search, off
 
 **Required:** `KAGI_API_TOKEN`
 
-Enrichment APIs require API access and consume API credit.
+Enrichment currently uses Kagi's legacy `/api/v0` API with `Bot` auth. It requires API access and consumes API credit.
 
 ## Subcommands
 

docs/commands/extract.mdx

@@ -21,9 +21,9 @@ The command uses JSON mode internally because that is the stable envelope return
 
 ## Authentication
 
-**Required:** `KAGI_API_TOKEN`
+**Required:** `KAGI_API_KEY`
 
-Extract is part of Kagi's paid API surface and consumes API credit per request.
+Extract is part of Kagi's current `/api/v1` paid API surface, uses `Bearer` auth, and consumes API credit per request.
 
 ## Arguments
 

docs/commands/fastgpt.mdx

@@ -27,7 +27,7 @@ The `kagi fastgpt` command queries Kagi's FastGPT API, which provides quick, fac
 
 **Required:** `KAGI_API_TOKEN`
 
-FastGPT requires API access and consumes API credit per request.
+FastGPT currently uses Kagi's legacy `/api/v0` API with `Bot` auth. It requires API access and consumes API credit per request.
 
 ## Arguments
 

docs/commands/mcp.mdx

@@ -17,7 +17,7 @@ kagi mcp
 
 - `kagi_search` - search Kagi
 - `kagi_summarize` - summarize a URL or text through the public API
-- `kagi_extract` - extract a page's full content as markdown through the paid Extract API. Accepts `url`.
+- `kagi_extract` - extract a page's full content as markdown through the current `/api/v1` Extract API. Uses `KAGI_API_KEY` directly and rejects session-only auth when Kagi's API portal does not allow Extract access. Accepts `url`.
 - `kagi_quick` - get a Kagi Quick Answer
 - `kagi_news` - fetch Kagi News stories (no auth required). Accepts `category` (default `world`), `limit` (default `12`), and `lang` (default `default`).
 - `kagi_news_search` - search the News tab of kagi.com and return story clusters (session token required). Accepts `query`, optional `region`, `freshness` (`day`/`week`/`month`), `order` (`default`/`recency`/`website`), and `limit`.

docs/commands/search.mdx

@@ -38,7 +38,7 @@ This matters because the Kagi Search API is still base-search only in this CLI.
 Plain base search keeps the existing repo behavior:
 
 - default session-first search when a session token is available
-- API-first only when you explicitly configure `[auth.preferred_auth] = "api"`
+- API-first only when you configure `[auth.preferred_auth] = "api"` and provide `KAGI_API_KEY`
 - session fallback only when the API path was selected first and rejected
 
 ### Filtered Search