This commit is contained in:
Mateo Wang 2026-10-27 16:03:35 -07:00 • committed by GitHub
commit 2cd197d1b5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 165 additions and 60 deletions

View file

@ -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 = (

View file

@ -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

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 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

View file

@ -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,9 @@ _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})
KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'"
KEYRING_ENABLE_HINT: Final = "keyring --enable (or unset PYTHON_KEYRING_BACKEND)"
@ -1033,10 +1035,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. 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.
"""
vault: Final = context_secret_vault(ctx)
token_data: Final = load_token(vault=vault)
@ -1055,7 +1059,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 +1115,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) or not base_url:
return True
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 in _PROXY_REJECTED_KEY_STATUSES
def _key_expiry_line(expires_at: float, renews: bool) -> str:

View file

@ -3,13 +3,15 @@ import os
import stat
import time
from pathlib import Path
from typing import Final
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 (
DISABLE_KEYRING_ENV_VAR,
KeyringDisabled,
@ -56,6 +58,20 @@ 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: 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:
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:
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 +712,32 @@ 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"""
token_data = CliTokenRecord(
@pytest.mark.parametrize(
("proxy_status", "expected_last_line_start"),
[
(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_start: str
):
_register_models_answer("sk-live", proxy_status)
token_data: Final = 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=STALE_TOKEN_TIMESTAMP,
)
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 "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].startswith(expected_last_line_start)
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 +1050,93 @@ 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={})
result: Final = 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"),
(403, 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", ""),
],
)
@responses.activate
def test_key_older_than_the_client_window_is_judged_by_the_proxy(
self,
proxy_answer: int | Exception,
expected_exit_code: int,
expected_stdout: str,
expected_stderr: str,
):
_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=STALE_TOKEN_TIMESTAMP,
),
patch("requests.post") as mock_post,
):
result = self.runner.invoke(print_token, obj={})
result: Final = 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
@responses.activate
def test_proxy_check_waits_only_a_few_seconds_for_a_silent_proxy(self):
_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=STALE_TOKEN_BASE_URL,
key="sk-stale-key",
timestamp=STALE_TOKEN_TIMESTAMP,
),
):
result: Final = self.runner.invoke(print_token, obj={})
timeout: Final = responses.calls[0].request.req_kwargs["timeout"]
assert result.exit_code == 0
assert result.stdout == "sk-stale-key\n"
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:
@ -2019,18 +2087,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": STALE_TOKEN_TIMESTAMP,
"expires_at": STALE_TOKEN_TIMESTAMP + 3600,
},
),
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 "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 == []