From 91402ec124b8753cff80d805e0a7f4d837ae7340 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 18:07:08 -0700 Subject: [PATCH 1/7] test(cli): print-token and whoami let the proxy judge a classic token past the client window --- .../proxy/client/cli/test_auth_commands.py | 115 ++++++++++++------ 1 file changed, 75 insertions(+), 40 deletions(-) diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index cb1fcba9df7..d3f87d852cc 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -6,8 +6,10 @@ from pathlib import Path from unittest.mock import Mock, patch import pytest +import requests import responses from click.testing import CliRunner +from responses import matchers from litellm.constants import CLI_JWT_EXPIRATION_HOURS from litellm.litellm_core_utils.cli_keyring import ( @@ -56,6 +58,19 @@ 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" + + +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}"})] + if isinstance(answer, Exception): + responses.get(models_url, body=answer, match=authorized) + else: + responses.get(models_url, json={"data": []}, status=answer, match=authorized) + responses.get(models_url, status=401) + + def _secret_blob(base_url: str, key: str) -> str: return json.dumps({"base_url": base_url, "key": key, "jwt_token": ""}) @@ -696,22 +711,30 @@ class TestWhoamiCommand: assert "Not authenticated" in result.output assert "Run 'lite login'" in result.output - def test_whoami_old_token(self): - """Test whoami with old token showing warning""" + @pytest.mark.parametrize( + ("proxy_status", "expected_last_line"), + [ + (200, f"Token age: {CLI_JWT_EXPIRATION_HOURS + 1:.1f} hours"), + (401, "Token expired. Run 'lite login' again."), + ], + ) + @responses.activate + def test_whoami_lets_the_proxy_judge_a_token_older_than_the_client_window(self, proxy_status, expected_last_line): + _register_models_answer("sk-live", proxy_status) token_data = CliTokenRecord( + base_url=STALE_TOKEN_BASE_URL, user_email="test@example.com", - user_id="test-user-123", - user_role="admin", key="sk-live", - timestamp=time.time() - (25 * 3600), + timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, ) with patch("litellm.proxy.client.cli.commands.auth.load_cli_token", return_value=token_data): result = self.runner.invoke(whoami) - assert result.exit_code == 0 - assert "Authenticated" in result.output - assert "Warning: Token is more than 24 hours old" in result.output + assert result.exit_code == 0 + assert result.output.splitlines()[-1] == expected_last_line + assert "Warning" not in result.output + assert len(responses.calls) == 1 def test_whoami_missing_fields(self): """Test whoami with token missing some fields""" @@ -1024,51 +1047,54 @@ class TestPrintTokenCommand: assert result.exit_code == 0 assert result.output.strip() == "sk-matches" + @responses.activate def test_fresh_cached_key_printed_without_network_call(self): """A recently-issued key should be printed straight from cache -- no refresh call on every single invocation (apiKeyHelper gets called frequently).""" - with ( - patch( - "litellm.proxy.client.cli.commands.auth.load_cli_token", - return_value=CliTokenRecord( - base_url="http://localhost:4000", - key="sk-cached-fresh", - timestamp=time.time(), - ), + with patch( + "litellm.proxy.client.cli.commands.auth.load_cli_token", + return_value=CliTokenRecord( + base_url="http://localhost:4000", + key="sk-cached-fresh", + timestamp=time.time(), ), - patch("requests.post") as mock_post, ): result = self.runner.invoke(print_token, obj={}) assert result.exit_code == 0 assert result.output.strip() == "sk-cached-fresh" - mock_post.assert_not_called() + assert len(responses.calls) == 0 - def test_stale_key_fails_fast_without_network_call(self): - """There is no silent refresh: an expired cached key must fail - loudly (stderr, nonzero exit) telling the user to `lite login` - again, rather than making a network call or printing a dead key - that will just 401 Claude Code.""" - old_timestamp = time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600 + @pytest.mark.parametrize( + ("proxy_answer", "expected_exit_code", "expected_stdout", "expected_stderr"), + [ + (200, 0, "sk-stale-key\n", ""), + (401, 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 + ): + _register_models_answer("sk-stale-key", proxy_answer) - with ( - patch( - "litellm.proxy.client.cli.commands.auth.load_cli_token", - return_value=CliTokenRecord( - base_url="http://localhost:4000", - key="sk-stale-key", - timestamp=old_timestamp, - ), + with patch( + "litellm.proxy.client.cli.commands.auth.load_cli_token", + return_value=CliTokenRecord( + base_url=STALE_TOKEN_BASE_URL, + key="sk-stale-key", + timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, ), - patch("requests.post") as mock_post, ): result = self.runner.invoke(print_token, obj={}) - assert result.exit_code != 0 - assert "sk-stale-key" not in result.output - assert "lite login" in result.output - mock_post.assert_not_called() + assert result.exit_code == expected_exit_code + assert result.stdout == expected_stdout + assert result.stderr == expected_stderr + assert len(responses.calls) == 1 class TestPrintTokenWithConfigFile: @@ -2019,18 +2045,27 @@ class TestPkcePrintToken: assert sum(len(session.posts) for session in _FakeSession.instances) == 1 assert save.call_count == 1 - def test_print_token_for_an_expired_classic_token_makes_no_request(self): + @responses.activate + def test_print_token_trusts_a_recorded_expiry_without_asking_the_proxy(self): + _register_models_answer("sk-classic", 200) with ( patch( "litellm.proxy.client.cli.commands.auth.load_token", - return_value={"key": "sk-classic", "timestamp": time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600}, + return_value={ + "key": "sk-classic", + "base_url": STALE_TOKEN_BASE_URL, + "timestamp": time.time() - 3600, + "expires_at": time.time() - 60, + }, ), patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession), ): result = self.runner.invoke(print_token, obj={}) assert result.exit_code == 1 - assert "Token expired" in result.output + assert result.stdout == "" + assert result.stderr == "Token expired. Run 'lite login' again.\n" + assert len(responses.calls) == 0 assert _FakeSession.instances == [] From e2ce86bdff2351ba72412832e87905aeb1378eeb Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 18:19:04 -0700 Subject: [PATCH 2/7] fix(cli): let the proxy decide when a classic lite login token has expired --- litellm/litellm_core_utils/cli_token_utils.py | 6 +-- litellm/proxy/client/cli/commands/auth.py | 43 +++++++++++++++---- 2 files changed, 38 insertions(+), 11 deletions(-) diff --git a/litellm/litellm_core_utils/cli_token_utils.py b/litellm/litellm_core_utils/cli_token_utils.py index ffe2c4433a0..37ed4efa0ca 100644 --- a/litellm/litellm_core_utils/cli_token_utils.py +++ b/litellm/litellm_core_utils/cli_token_utils.py @@ -353,9 +353,9 @@ def is_cli_token_fresh( buffer_hours: float = CLI_TOKEN_FRESHNESS_BUFFER_SECONDS / 3600, ) -> bool: """Check whether a cached CLI token is still within its expiration window. - Used by `lite auth print-token` to fail fast, without a network round trip, - once the cached token is past `LITELLM_CLI_JWT_EXPIRATION_HOURS`. A `--pkce` - credential carries its own `expires_at`, which is authoritative when present.""" + Used by `lite auth print-token` to skip asking the proxy while the cached token + is younger than `LITELLM_CLI_JWT_EXPIRATION_HOURS`. A `--pkce` credential + carries its own `expires_at`, which is authoritative when present.""" from litellm.constants import CLI_JWT_EXPIRATION_HOURS expires_at: Final = ( diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index b5302d1f561..2b6289234d4 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -13,7 +13,6 @@ from rich.console import Console from rich.table import Table from typing_extensions import NotRequired, ReadOnly, TypedDict, assert_never -from litellm.constants import CLI_JWT_EXPIRATION_HOURS from litellm.litellm_core_utils.cli_keyring import ( DISABLE_KEYRING_ENV_VAR, SYSTEM_KEYRING, @@ -143,6 +142,8 @@ _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 + KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'" KEYRING_ENABLE_HINT: Final = "keyring --enable (or unset PYTHON_KEYRING_BACKEND)" @@ -1033,10 +1034,12 @@ def print_token(ctx: click.Context): Designed to be used as Claude Code's `apiKeyHelper` (https://docs.claude.com/en/docs/claude-code/settings): stdout must - contain only the token, so all diagnostics go to stderr. The token - expires after `LITELLM_CLI_JWT_EXPIRATION_HOURS` (default 24h); a - `lite login --pkce` token renews itself here first, and once a token - has expired for good, run the same `lite login` command again. + contain only the token, so all diagnostics go to stderr. The proxy + decides when its token expires: once the token is older than + `LITELLM_CLI_JWT_EXPIRATION_HOURS` (default 24h), it is checked against + the proxy and refused only if the proxy rejects it. A `lite login --pkce` + token renews itself here first, and once a token has expired for good, + run the same `lite login` command again. """ vault: Final = context_secret_vault(ctx) token_data: Final = load_token(vault=vault) @@ -1055,7 +1058,7 @@ def print_token(ctx: click.Context): sys.exit(1) renews: Final = "refresh_token" in token_data - if not is_cli_token_fresh(token_data) and not renews: + if not renews and _token_expired(token_data): click.echo("Token expired. Run 'lite login' again.", err=True) sys.exit(1) @@ -1111,8 +1114,32 @@ 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 age_hours > CLI_JWT_EXPIRATION_HOURS: - click.echo(f"Warning: Token is more than {CLI_JWT_EXPIRATION_HOURS} hours old and may have expired.") + elif _token_expired(token_data): + click.echo("Token expired. Run 'lite login' again.") + + +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)): + return True + return _proxy_rejects_key(token_data) + + +def _proxy_rejects_key(token_data: Mapping[str, object]) -> bool: + key: Final = token_data.get("key") + base_url: Final = token_data.get("base_url") + if not isinstance(key, str) or not isinstance(base_url, str): + return False + try: + response: Final = requests.get( + f"{base_url}/v1/models", + headers={"Authorization": f"Bearer {key}"}, + timeout=_PROXY_KEY_CHECK_TIMEOUT_SECONDS, + ) + except requests.RequestException: + return False + return response.status_code == 401 def _key_expiry_line(expires_at: float, renews: bool) -> str: From cb97a89dbe0defad5e43380207fa961e5fcc10b3 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 18:59:42 -0700 Subject: [PATCH 3/7] fix(cli): treat 403 and 404 as a rejected token and judge lite up logins the same way --- litellm/proxy/client/cli/README.md | 2 +- litellm/proxy/client/cli/commands/auth.py | 9 ++-- litellm/proxy/client/cli/commands/up.py | 13 +++-- .../proxy/client/cli/test_auth_commands.py | 29 +++++++---- .../unit/proxy/client/cli/test_up_commands.py | 48 +++++++++++++++---- 5 files changed, 74 insertions(+), 27 deletions(-) diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md index 842705ad5a7..934fecb1028 100644 --- a/litellm/proxy/client/cli/README.md +++ b/litellm/proxy/client/cli/README.md @@ -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 diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index 2b6289234d4..fb00e02dbdd 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -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: diff --git a/litellm/proxy/client/cli/commands/up.py b/litellm/proxy/client/cli/commands/up.py index 4043761f255..0c4e9bdcf25 100644 --- a/litellm/proxy/client/cli/commands/up.py +++ b/litellm/proxy/client/cli/commands/up.py @@ -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: diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index d3f87d852cc..cf01954c223 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -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 == "" diff --git a/tests/unit/proxy/client/cli/test_up_commands.py b/tests/unit/proxy/client/cli/test_up_commands.py index 5c2e726315b..99af1f36867 100644 --- a/tests/unit/proxy/client/cli/test_up_commands.py +++ b/tests/unit/proxy/client/cli/test_up_commands.py @@ -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"), From a757c076e2117139cb3eb04444ae50dc9e79fe21 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 19:57:47 -0700 Subject: [PATCH 4/7] fix(cli): keep lite up on the client window and bound the proxy check to 3 seconds --- litellm/proxy/client/cli/README.md | 2 +- litellm/proxy/client/cli/commands/auth.py | 2 +- litellm/proxy/client/cli/commands/up.py | 13 ++--- .../proxy/client/cli/test_auth_commands.py | 19 ++++++++ .../unit/proxy/client/cli/test_up_commands.py | 48 ++++--------------- 5 files changed, 33 insertions(+), 51 deletions(-) diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md index 934fecb1028..f5060aa9af6 100644 --- a/litellm/proxy/client/cli/README.md +++ b/litellm/proxy/client/cli/README.md @@ -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 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. +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` and `lite whoami` ask the proxy whether it still accepts the token instead of assuming it expired. `lite up` still starts a new login at that point, since it copies the token into Claude Code's settings as a static key that it never renews. `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 diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index fb00e02dbdd..41f80d361dc 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -142,7 +142,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_KEY_CHECK_TIMEOUT_SECONDS: Final = 3 _PROXY_REJECTED_KEY_STATUSES: Final = frozenset({401, 403, 404}) KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'" diff --git a/litellm/proxy/client/cli/commands/up.py b/litellm/proxy/client/cli/commands/up.py index 0c4e9bdcf25..4043761f255 100644 --- a/litellm/proxy/client/cli/commands/up.py +++ b/litellm/proxy/client/cli/commands/up.py @@ -15,18 +15,11 @@ 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, - token_expired, -) +from .auth import CliContextObj, cli_context_obj, context_secret_vault, get_stored_api_key, load_token, login from .claude_settings import ( BACKUP_PATH, CLAUDE_SETTINGS_PATH, @@ -118,7 +111,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 not token_expired(token_data) + return token_data is not None and is_cli_token_fresh(token_data) def _key_resolved_on_the_way_in(ctx_obj: CliContextObj, base_url: str, vault: SecretVault) -> str | None: diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index cf01954c223..33717f2bd60 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -1105,6 +1105,25 @@ class TestPrintTokenCommand: assert result.stderr == expected_stderr assert len(responses.calls) == 1 + @responses.activate + def test_proxy_check_waits_only_a_few_seconds_for_a_silent_proxy(self): + _register_models_answer("sk-stale-key", 200) + + with patch( + "litellm.proxy.client.cli.commands.auth.load_cli_token", + return_value=CliTokenRecord( + base_url=STALE_TOKEN_BASE_URL, + key="sk-stale-key", + timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, + ), + ): + result: Final = self.runner.invoke(print_token, obj={}) + + timeout: Final = responses.calls[0].request.req_kwargs["timeout"] + assert result.exit_code == 0 + assert isinstance(timeout, int | float) + assert 0 < timeout <= 5 + class TestPrintTokenWithConfigFile: """A config-file base_url is a drop-in replacement for exporting diff --git a/tests/unit/proxy/client/cli/test_up_commands.py b/tests/unit/proxy/client/cli/test_up_commands.py index 99af1f36867..5c2e726315b 100644 --- a/tests/unit/proxy/client/cli/test_up_commands.py +++ b/tests/unit/proxy/client/cli/test_up_commands.py @@ -3,15 +3,12 @@ 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 @@ -305,7 +302,7 @@ class TestEnsureFreshLogin: _FakeTokenStore( monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {"http://proxy-a:4000": "sk-a"} ) - monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) + monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) login_calls = _capture_login(monkeypatch) ensure_fresh_login(_make_ctx("http://proxy-a:4000")) @@ -315,7 +312,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, "token_expired", lambda token_data: False) + monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) login_calls = _capture_login( monkeypatch, on_login=lambda: store.log_in({"key": "sk-b", "base_url": "http://proxy-b:4000"}, "sk-b") ) @@ -328,7 +325,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, "token_expired", lambda token_data: False) + monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) login_calls = _capture_login( monkeypatch, on_login=lambda: store.log_in({"key": "sk-a", "base_url": "http://proxy-a:4000"}, "sk-a"), @@ -341,38 +338,11 @@ 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, "token_expired", lambda token_data: False) + monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) 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.""" @@ -406,7 +376,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, "token_expired", lambda token_data: False) + monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) monkeypatch.setattr(up_module, "pkce_default", lambda: True) login_calls = _capture_login( monkeypatch, @@ -420,7 +390,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, "token_expired", lambda token_data: False) + monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) monkeypatch.setattr(up_module, "pkce_default", lambda: True) with pytest.raises(UpError, match="Run `lite login --pkce` first"): @@ -485,7 +455,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}.token_expired", return_value=False), + patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True), patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"), patch(f"{UP_MODULE}.verify_proxy_key"), ): @@ -516,7 +486,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}.token_expired", return_value=False), + patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True), patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"), patch( f"{UP_MODULE}.verify_proxy_key", @@ -545,7 +515,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}.token_expired", return_value=False), + patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True), patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"), patch(f"{UP_MODULE}.verify_proxy_key"), patch(f"{UP_MODULE}.signal.signal"), From 44eb40d855e2167b338acbd31b177db33fa59a2c Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 20:36:55 -0700 Subject: [PATCH 5/7] test(cli): prove the proxy check gives up on a silent proxy and pin stale fixtures Point the timeout test at a local socket that never answers, use fixed timestamps for stale CLI token fixtures, and correct the print-token docs for tokens younger than the client window. --- litellm/proxy/client/README.md | 4 ++-- litellm/proxy/client/cli/README.md | 2 +- litellm/proxy/client/cli/commands/auth.py | 8 +++---- .../proxy/client/cli/test_auth_commands.py | 24 +++++++++---------- 4 files changed, 19 insertions(+), 19 deletions(-) diff --git a/litellm/proxy/client/README.md b/litellm/proxy/client/README.md index 1fff68677cc..ceec636567f 100644 --- a/litellm/proxy/client/README.md +++ b/litellm/proxy/client/README.md @@ -342,7 +342,7 @@ The CLI provides these authentication commands: - **`lite login --pkce`** - Sign in through the system browser with OAuth authorization code + PKCE; the key renews itself with a refresh token - **`lite logout`** - Clear stored authentication token (and revoke a `--pkce` refresh token on the proxy) - **`lite whoami`** - Show current authentication status -- **`lite auth print-token`** - Print the cached token (used as Claude Code's `apiKeyHelper`); renews a `--pkce` key first and fails once a classic token has expired +- **`lite auth print-token`** - Print the cached token (used as Claude Code's `apiKeyHelper`); renews a `--pkce` key first, and fails once a classic token is past 24 hours and the proxy rejects it ### Authentication Flow Steps @@ -382,7 +382,7 @@ Keychain storage needs the `keyring` package, which ships with `pip install 'lit `lite logout` clears both stores. If the keychain is locked at that moment it says so, and re-running it once the keychain is unlocked finishes the job. -The stored credential is a short-lived, per-session agent token, not a managed virtual key. It is scoped to the user and team you logged in as and inherits their models and budgets; spend is tracked against the shared team and user budgets rather than a separate per-session cap, so multiple logins or several concurrent agents all draw down the same allowance. It is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); re-run `lite login` to refresh it and pick up your latest team and user settings. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while fresh and fails once it expires -- there is no silent renewal. It is accepted on a default deployment without `EXPERIMENTAL_UI_LOGIN`, does not appear in the Keys UI, and cannot be rotated or revoked mid-session. A credential from `lite login --pkce` is the exception: it carries a refresh token, so the CLI renews the key shortly before it expires and `lite logout` revokes the refresh token on the proxy (see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). 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. For a long-lived, rotatable, Keys-UI-visible credential, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY`. +The stored credential is a short-lived, per-session agent token, not a managed virtual key. It is scoped to the user and team you logged in as and inherits their models and budgets; spend is tracked against the shared team and user budgets rather than a separate per-session cap, so multiple logins or several concurrent agents all draw down the same allowance. It is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); re-run `lite login` to refresh it and pick up your latest team and user settings. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it, and once it is past 24 hours (or the client's `LITELLM_CLI_JWT_EXPIRATION_HOURS`) asks the proxy first and fails if the proxy rejects it. There is no silent renewal. It is accepted on a default deployment without `EXPERIMENTAL_UI_LOGIN`, does not appear in the Keys UI, and cannot be rotated or revoked mid-session. A credential from `lite login --pkce` is the exception: it carries a refresh token, so the CLI renews the key shortly before it expires and `lite logout` revokes the refresh token on the proxy (see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). 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. For a long-lived, rotatable, Keys-UI-visible credential, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY`. ### Usage diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md index f5060aa9af6..039f499e75f 100644 --- a/litellm/proxy/client/cli/README.md +++ b/litellm/proxy/client/cli/README.md @@ -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 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` and `lite whoami` ask the proxy whether it still accepts the token instead of assuming it expired. `lite up` still starts a new login at that point, since it copies the token into Claude Code's settings as a static key that it never renews. `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. +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 without asking the proxy for its first 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client. After that, `print-token` and `lite whoami` ask the proxy whether it still accepts the token, and `print-token` fails once the proxy rejects it. There is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. If the proxy's tokens last less than 24 hours, set the same `LITELLM_CLI_JWT_EXPIRATION_HOURS` on the client so `print-token` stops printing the token once it runs out. `lite up` still starts a new login after 24 hours. It copies the token into Claude Code's settings as a static key that it never renews, so a fresh login gives Claude Code the proxy's full token lifetime instead of whatever an old token has left. `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 diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index 41f80d361dc..db4787040ce 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -1035,10 +1035,10 @@ def print_token(ctx: click.Context): Designed to be used as Claude Code's `apiKeyHelper` (https://docs.claude.com/en/docs/claude-code/settings): stdout must - contain only the token, so all diagnostics go to stderr. The proxy - decides when its token expires: once the token is older than - `LITELLM_CLI_JWT_EXPIRATION_HOURS` (default 24h), it is checked against - the proxy and refused only if the proxy rejects it. A `lite login --pkce` + contain only the token, so all diagnostics go to stderr. A token younger + than `LITELLM_CLI_JWT_EXPIRATION_HOURS` (default 24h) is printed without + asking the proxy. An older one is checked against the proxy and refused + only if the proxy rejects it. A `lite login --pkce` token renews itself here first, and once a token has expired for good, run the same `lite login` command again. """ diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index 33717f2bd60..0872457e4ec 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -1,5 +1,6 @@ import json import os +import socket import stat import time from pathlib import Path @@ -60,6 +61,7 @@ def _write_token_file(home: Path, *, key: str | None) -> None: STALE_TOKEN_BASE_URL: Final = "https://stale-token.example.com" +STALE_TOKEN_TIMESTAMP: Final = 1_700_000_000.0 def _register_models_answer(key: str, answer: int | Exception) -> None: @@ -1095,7 +1097,7 @@ class TestPrintTokenCommand: return_value=CliTokenRecord( base_url=STALE_TOKEN_BASE_URL, key="sk-stale-key", - timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, + timestamp=STALE_TOKEN_TIMESTAMP, ), ): result: Final = self.runner.invoke(print_token, obj={}) @@ -1105,24 +1107,22 @@ class TestPrintTokenCommand: assert result.stderr == expected_stderr assert len(responses.calls) == 1 - @responses.activate def test_proxy_check_waits_only_a_few_seconds_for_a_silent_proxy(self): - _register_models_answer("sk-stale-key", 200) - - with patch( + with socket.create_server(("127.0.0.1", 0)) as silent_proxy, patch( "litellm.proxy.client.cli.commands.auth.load_cli_token", return_value=CliTokenRecord( - base_url=STALE_TOKEN_BASE_URL, + base_url=f"http://127.0.0.1:{silent_proxy.getsockname()[1]}", key="sk-stale-key", - timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, + timestamp=STALE_TOKEN_TIMESTAMP, ), ): + started: Final = time.monotonic() result: Final = self.runner.invoke(print_token, obj={}) + elapsed: Final = time.monotonic() - started - timeout: Final = responses.calls[0].request.req_kwargs["timeout"] assert result.exit_code == 0 - assert isinstance(timeout, int | float) - assert 0 < timeout <= 5 + assert result.stdout == "sk-stale-key\n" + assert elapsed < 5 class TestPrintTokenWithConfigFile: @@ -2082,8 +2082,8 @@ class TestPkcePrintToken: return_value={ "key": "sk-classic", "base_url": STALE_TOKEN_BASE_URL, - "timestamp": time.time() - 3600, - "expires_at": time.time() - 60, + "timestamp": STALE_TOKEN_TIMESTAMP, + "expires_at": STALE_TOKEN_TIMESTAMP + 3600, }, ), patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession), From 4310791550845562bf2f4786a88ecf78b62c9415 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 21:04:12 -0700 Subject: [PATCH 6/7] fix(cli): expire a CLI token with no recorded proxy and stop treating 404 as rejected A token file without base_url cannot be checked, so it keeps the client window's verdict instead of printing forever. A 404 also comes from a proxy that does not serve /v1/models, so only 401 and 403 count as a rejected key, matching the CLI's existing key check. The timeout test now runs in process. --- litellm/proxy/client/cli/commands/auth.py | 6 ++-- .../proxy/client/cli/test_auth_commands.py | 29 ++++++++++++++----- 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index db4787040ce..e38f54adc4f 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -143,7 +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 = 3 -_PROXY_REJECTED_KEY_STATUSES: Final = frozenset({401, 403, 404}) +_PROXY_REJECTED_KEY_STATUSES: Final = frozenset({401, 403}) KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'" @@ -1130,8 +1130,8 @@ def token_expired(token_data: Mapping[str, object]) -> bool: def _proxy_rejects_key(token_data: Mapping[str, object]) -> bool: key: Final = token_data.get("key") base_url: Final = token_data.get("base_url") - if not isinstance(key, str) or not isinstance(base_url, str): - return False + if not isinstance(key, str) or not isinstance(base_url, str) or not base_url: + return True try: response: Final = requests.get( f"{base_url}/v1/models", diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index 0872457e4ec..fbababa0d2d 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -1,6 +1,5 @@ import json import os -import socket import stat import time from pathlib import Path @@ -1077,7 +1076,7 @@ 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"), + (404, 0, "sk-stale-key\n", ""), (500, 0, "sk-stale-key\n", ""), (requests.ConnectionError("proxy unreachable"), 0, "sk-stale-key\n", ""), ], @@ -1107,22 +1106,38 @@ class TestPrintTokenCommand: assert result.stderr == expected_stderr assert len(responses.calls) == 1 + @responses.activate def test_proxy_check_waits_only_a_few_seconds_for_a_silent_proxy(self): - with socket.create_server(("127.0.0.1", 0)) as silent_proxy, patch( + _register_models_answer("sk-stale-key", requests.ReadTimeout("proxy sent nothing")) + + with patch( "litellm.proxy.client.cli.commands.auth.load_cli_token", return_value=CliTokenRecord( - base_url=f"http://127.0.0.1:{silent_proxy.getsockname()[1]}", + base_url=STALE_TOKEN_BASE_URL, key="sk-stale-key", timestamp=STALE_TOKEN_TIMESTAMP, ), ): - started: Final = time.monotonic() result: Final = self.runner.invoke(print_token, obj={}) - elapsed: Final = time.monotonic() - started + timeout: Final = responses.calls[0].request.req_kwargs["timeout"] assert result.exit_code == 0 assert result.stdout == "sk-stale-key\n" - assert elapsed < 5 + assert isinstance(timeout, int | float) + assert 0 < timeout <= 5 + + @responses.activate + def test_key_without_a_recorded_proxy_still_expires_after_the_client_window(self): + with patch( + "litellm.proxy.client.cli.commands.auth.load_cli_token", + return_value=CliTokenRecord(key="sk-old-format", timestamp=STALE_TOKEN_TIMESTAMP), + ): + result: Final = self.runner.invoke(print_token, obj={}) + + assert result.exit_code == 1 + assert result.stdout == "" + assert result.stderr == "Token expired. Run 'lite login' again.\n" + assert len(responses.calls) == 0 class TestPrintTokenWithConfigFile: From 898705d0314cae6b13b08bf7199c61d8612bfd14 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 21:30:26 -0700 Subject: [PATCH 7/7] test(cli): judge the whoami proxy check on a fixed timestamp and name the client window for lite up --- litellm/proxy/client/cli/README.md | 2 +- tests/unit/proxy/client/cli/test_auth_commands.py | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md index 039f499e75f..82014bf2e09 100644 --- a/litellm/proxy/client/cli/README.md +++ b/litellm/proxy/client/cli/README.md @@ -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 without asking the proxy for its first 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client. After that, `print-token` and `lite whoami` ask the proxy whether it still accepts the token, and `print-token` fails once the proxy rejects it. There is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. If the proxy's tokens last less than 24 hours, set the same `LITELLM_CLI_JWT_EXPIRATION_HOURS` on the client so `print-token` stops printing the token once it runs out. `lite up` still starts a new login after 24 hours. It copies the token into Claude Code's settings as a static key that it never renews, so a fresh login gives Claude Code the proxy's full token lifetime instead of whatever an old token has left. `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. +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 without asking the proxy for its first 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client. After that, `print-token` and `lite whoami` ask the proxy whether it still accepts the token, and `print-token` fails once the proxy rejects it. There is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. If the proxy's tokens last less than 24 hours, set the same `LITELLM_CLI_JWT_EXPIRATION_HOURS` on the client so `print-token` stops printing the token once it runs out. `lite up` still starts a new login once the token is older than that same client window. It copies the token into Claude Code's settings as a static key that it never renews, so a fresh login gives Claude Code the proxy's full token lifetime instead of whatever an old token has left. `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 diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index fbababa0d2d..5d5ebcf5dfd 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -12,7 +12,6 @@ import responses from click.testing import CliRunner from responses import matchers -from litellm.constants import CLI_JWT_EXPIRATION_HOURS from litellm.litellm_core_utils.cli_keyring import ( DISABLE_KEYRING_ENV_VAR, KeyringDisabled, @@ -714,29 +713,29 @@ class TestWhoamiCommand: assert "Run 'lite login'" in result.output @pytest.mark.parametrize( - ("proxy_status", "expected_last_line"), + ("proxy_status", "expected_last_line_start"), [ - (200, f"Token age: {CLI_JWT_EXPIRATION_HOURS + 1:.1f} hours"), + (200, "Token age: "), (401, "Token expired. Run 'lite login' again."), ], ) @responses.activate def test_whoami_lets_the_proxy_judge_a_token_older_than_the_client_window( - self, proxy_status: int, expected_last_line: str + self, proxy_status: int, expected_last_line_start: str ): _register_models_answer("sk-live", proxy_status) token_data: Final = CliTokenRecord( base_url=STALE_TOKEN_BASE_URL, user_email="test@example.com", key="sk-live", - timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, + timestamp=STALE_TOKEN_TIMESTAMP, ) with patch("litellm.proxy.client.cli.commands.auth.load_cli_token", return_value=token_data): result: Final = self.runner.invoke(whoami) assert result.exit_code == 0 - assert result.output.splitlines()[-1] == expected_last_line + assert result.output.splitlines()[-1].startswith(expected_last_line_start) assert "Warning" not in result.output assert len(responses.calls) == 1