fix(cli): treat 403 and 404 as a rejected token and judge lite up logins the same way

This commit is contained in:
mateo-berri 2026-10-20 18:59:42 -07:00
parent e2ce86bdff
commit cb97a89dbe
5 changed files with 74 additions and 27 deletions

View file

@ -506,7 +506,7 @@ To pin the model, pass the agent's own model flag (for example `lite claude --mo
The token minted by `lite login` is a short-lived, per-session agent credential, not a managed virtual key. It is scoped to the user and team you authenticated as, inherits that user's and team's models and budgets, and is enforced on the proxy exactly like a virtual key on the same team (guardrails, routing, logging, spend). Spend is tracked against the shared team and user budgets, so running several agents (or logging in more than once) does not hand each session its own separate budget; they all draw down the same team/user allowance. There is no separate per-session cap, so sustained agent use is not capped at a small chat-session limit.
The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while it's still fresh and fails once it expires -- there is no silent renewal, so a long-running session needs a fresh `lite login` once a day. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the daily re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it until the proxy stops accepting it and then fails -- there is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. Past 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client, `print-token`, `lite whoami`, and `lite up` ask the proxy whether it still accepts the token instead of assuming it expired. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead.
### Route Every Claude Code Session Through the Proxy

View file

@ -143,6 +143,7 @@ _TeamMapping: Final = TypeVar("_TeamMapping", bound=Mapping[str, object])
_JSON_OBJECT: Final = TypeAdapter(Mapping[str, object], config=ConfigDict(hide_input_in_errors=True))
_PROXY_KEY_CHECK_TIMEOUT_SECONDS: Final = 10
_PROXY_REJECTED_KEY_STATUSES: Final = frozenset({401, 403, 404})
KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'"
@ -1058,7 +1059,7 @@ def print_token(ctx: click.Context):
sys.exit(1)
renews: Final = "refresh_token" in token_data
if not renews and _token_expired(token_data):
if not renews and token_expired(token_data):
click.echo("Token expired. Run 'lite login' again.", err=True)
sys.exit(1)
@ -1114,11 +1115,11 @@ def whoami(ctx: click.Context):
expires_at: Final = token_data.get("expires_at")
if isinstance(expires_at, (int, float)):
click.echo(_key_expiry_line(expires_at, renews="refresh_token" in token_data))
elif _token_expired(token_data):
elif token_expired(token_data):
click.echo("Token expired. Run 'lite login' again.")
def _token_expired(token_data: Mapping[str, object]) -> bool:
def token_expired(token_data: Mapping[str, object]) -> bool:
if is_cli_token_fresh(token_data):
return False
if isinstance(token_data.get("expires_at"), (int, float)):
@ -1139,7 +1140,7 @@ def _proxy_rejects_key(token_data: Mapping[str, object]) -> bool:
)
except requests.RequestException:
return False
return response.status_code == 401
return response.status_code in _PROXY_REJECTED_KEY_STATUSES
def _key_expiry_line(expires_at: float, renews: bool) -> str:

View file

@ -15,11 +15,18 @@ import click
from pydantic import JsonValue, TypeAdapter, ValidationError
from litellm.litellm_core_utils.cli_keyring import SecretVault
from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh
from litellm.litellm_core_utils.private_json import ensure_private_dir
from .agents import AgentRunError, resolve_api_key, verify_proxy_key
from .auth import CliContextObj, cli_context_obj, context_secret_vault, get_stored_api_key, load_token, login
from .auth import (
CliContextObj,
cli_context_obj,
context_secret_vault,
get_stored_api_key,
load_token,
login,
token_expired,
)
from .claude_settings import (
BACKUP_PATH,
CLAUDE_SETTINGS_PATH,
@ -111,7 +118,7 @@ def _usable_login(api_key: str | None, vault: SecretVault) -> bool:
if api_key is None:
return False
token_data: Final = load_token(vault=vault)
return token_data is not None and is_cli_token_fresh(token_data)
return token_data is not None and not token_expired(token_data)
def _key_resolved_on_the_way_in(ctx_obj: CliContextObj, base_url: str, vault: SecretVault) -> str | None:

View file

@ -3,6 +3,7 @@ import os
import stat
import time
from pathlib import Path
from typing import Final
from unittest.mock import Mock, patch
import pytest
@ -58,12 +59,12 @@ def _write_token_file(home: Path, *, key: str | None) -> None:
_write_home_json(home, "token.json", payload if key is None else {**payload, "key": key})
STALE_TOKEN_BASE_URL = "https://stale-token.example.com"
STALE_TOKEN_BASE_URL: Final = "https://stale-token.example.com"
def _register_models_answer(key: str, answer: int | Exception) -> None:
models_url = f"{STALE_TOKEN_BASE_URL}/v1/models"
authorized = [matchers.header_matcher({"Authorization": f"Bearer {key}"})]
models_url: Final = f"{STALE_TOKEN_BASE_URL}/v1/models"
authorized: Final = [matchers.header_matcher({"Authorization": f"Bearer {key}"})]
if isinstance(answer, Exception):
responses.get(models_url, body=answer, match=authorized)
else:
@ -719,9 +720,11 @@ class TestWhoamiCommand:
],
)
@responses.activate
def test_whoami_lets_the_proxy_judge_a_token_older_than_the_client_window(self, proxy_status, expected_last_line):
def test_whoami_lets_the_proxy_judge_a_token_older_than_the_client_window(
self, proxy_status: int, expected_last_line: str
):
_register_models_answer("sk-live", proxy_status)
token_data = CliTokenRecord(
token_data: Final = CliTokenRecord(
base_url=STALE_TOKEN_BASE_URL,
user_email="test@example.com",
key="sk-live",
@ -729,7 +732,7 @@ class TestWhoamiCommand:
)
with patch("litellm.proxy.client.cli.commands.auth.load_cli_token", return_value=token_data):
result = self.runner.invoke(whoami)
result: Final = self.runner.invoke(whoami)
assert result.exit_code == 0
assert result.output.splitlines()[-1] == expected_last_line
@ -1060,7 +1063,7 @@ class TestPrintTokenCommand:
timestamp=time.time(),
),
):
result = self.runner.invoke(print_token, obj={})
result: Final = self.runner.invoke(print_token, obj={})
assert result.exit_code == 0
assert result.output.strip() == "sk-cached-fresh"
@ -1071,13 +1074,19 @@ class TestPrintTokenCommand:
[
(200, 0, "sk-stale-key\n", ""),
(401, 1, "", "Token expired. Run 'lite login' again.\n"),
(403, 1, "", "Token expired. Run 'lite login' again.\n"),
(404, 1, "", "Token expired. Run 'lite login' again.\n"),
(500, 0, "sk-stale-key\n", ""),
(requests.ConnectionError("proxy unreachable"), 0, "sk-stale-key\n", ""),
],
)
@responses.activate
def test_key_older_than_the_client_window_is_judged_by_the_proxy(
self, proxy_answer, expected_exit_code, expected_stdout, expected_stderr
self,
proxy_answer: int | Exception,
expected_exit_code: int,
expected_stdout: str,
expected_stderr: str,
):
_register_models_answer("sk-stale-key", proxy_answer)
@ -1089,7 +1098,7 @@ class TestPrintTokenCommand:
timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600,
),
):
result = self.runner.invoke(print_token, obj={})
result: Final = self.runner.invoke(print_token, obj={})
assert result.exit_code == expected_exit_code
assert result.stdout == expected_stdout
@ -2060,7 +2069,7 @@ class TestPkcePrintToken:
),
patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession),
):
result = self.runner.invoke(print_token, obj={})
result: Final = self.runner.invoke(print_token, obj={})
assert result.exit_code == 1
assert result.stdout == ""

View file

@ -3,12 +3,15 @@ import shutil
import stat
import sys
import time
from typing import Final
from unittest.mock import patch
import click
import pytest
import responses
from click.testing import CliRunner
from litellm.constants import CLI_JWT_EXPIRATION_HOURS
from litellm.proxy.client.cli.commands import up as up_module
from litellm.proxy.client.cli.commands.agents import AgentRunError
from litellm.proxy.client.cli.commands.claude_settings import ClaudeSettingsError, StaticToken
@ -302,7 +305,7 @@ class TestEnsureFreshLogin:
_FakeTokenStore(
monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {"http://proxy-a:4000": "sk-a"}
)
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
login_calls = _capture_login(monkeypatch)
ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
@ -312,7 +315,7 @@ class TestEnsureFreshLogin:
def test_forces_a_fresh_login_when_the_cached_token_is_for_a_different_proxy(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
login_calls = _capture_login(
monkeypatch, on_login=lambda: store.log_in({"key": "sk-b", "base_url": "http://proxy-b:4000"}, "sk-b")
)
@ -325,7 +328,7 @@ class TestEnsureFreshLogin:
def test_forces_a_fresh_login_when_the_cached_token_has_no_readable_key(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
store = _FakeTokenStore(monkeypatch, {"base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
login_calls = _capture_login(
monkeypatch,
on_login=lambda: store.log_in({"key": "sk-a", "base_url": "http://proxy-a:4000"}, "sk-a"),
@ -338,11 +341,38 @@ class TestEnsureFreshLogin:
def test_fails_cleanly_non_interactively_when_only_a_different_proxys_token_is_cached(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
_FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
with pytest.raises(UpError, match="Run `lite login` first"):
ensure_fresh_login(_make_ctx("http://proxy-b:4000"))
@pytest.mark.parametrize(("proxy_status", "expected_login_calls"), [(200, []), (401, [("http://proxy-a:4000", False)])])
@responses.activate
def test_lets_the_proxy_judge_a_classic_token_older_than_the_client_window(
self, monkeypatch, proxy_status: int, expected_login_calls: list[tuple[str, bool]]
):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
responses.get("http://proxy-a:4000/v1/models", json={"data": []}, status=proxy_status)
store: Final = _FakeTokenStore(
monkeypatch,
{
"key": "sk-a",
"base_url": "http://proxy-a:4000",
"timestamp": time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600,
},
{"http://proxy-a:4000": "sk-a"},
)
login_calls: Final = _capture_login(
monkeypatch,
on_login=lambda: store.log_in(
{"key": "sk-new", "base_url": "http://proxy-a:4000", "timestamp": time.time()}, "sk-new"
),
)
ensure_fresh_login(_make_ctx("http://proxy-a:4000"))
assert login_calls == expected_login_calls
def test_trusts_a_pkce_credential_that_was_renewed_on_the_way_in(self, monkeypatch):
"""A --pkce key inside its freshness buffer is renewed by `get_stored_api_key`, so `lite up`
must judge the rotated record rather than refuse the one it started with."""
@ -376,7 +406,7 @@ class TestEnsureFreshLogin:
"""`lite config set pkce true` is honoured by the login `lite up` starts, not only by `lite login`."""
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True)
store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "pkce_default", lambda: True)
login_calls = _capture_login(
monkeypatch,
@ -390,7 +420,7 @@ class TestEnsureFreshLogin:
def test_names_the_pkce_login_in_the_non_interactive_error_when_the_saved_pkce_default_is_on(self, monkeypatch):
monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False)
_FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {})
monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True)
monkeypatch.setattr(up_module, "token_expired", lambda token_data: False)
monkeypatch.setattr(up_module, "pkce_default", lambda: True)
with pytest.raises(UpError, match="Run `lite login --pkce` first"):
@ -455,7 +485,7 @@ class TestUpCommand:
with (
patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
patch(f"{UP_MODULE}.token_expired", return_value=False),
patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.verify_proxy_key"),
):
@ -486,7 +516,7 @@ class TestUpCommand:
with (
patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
patch(f"{UP_MODULE}.token_expired", return_value=False),
patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
patch(
f"{UP_MODULE}.verify_proxy_key",
@ -515,7 +545,7 @@ class TestUpCommand:
with (
patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}),
patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True),
patch(f"{UP_MODULE}.token_expired", return_value=False),
patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"),
patch(f"{UP_MODULE}.verify_proxy_key"),
patch(f"{UP_MODULE}.signal.signal"),