From 2e0ad0446f7b2998bea68a5e494aa040c1fe77d9 Mon Sep 17 00:00:00 2001 From: HARSHAVARDHAN-RAJU5 Date: Thu, 17 Sep 2026 22:28:43 +0530 Subject: [PATCH 1/3] feat(proxy): add user_alias filter to /user/list Callers can now pass user_alias to GET /user/list to filter users by a case-insensitive partial alias match, the same way user_email already works. An empty value applies no filter. Regenerates the dashboard's schema.d.ts for the new query param. Closes #37472 --- .../internal_user_endpoints.py | 8 +++ .../test_internal_user_endpoints.py | 65 +++++++++++++++++++ ui/litellm-dashboard/src/lib/http/schema.d.ts | 4 ++ 3 files changed, 77 insertions(+) diff --git a/litellm/proxy/management_endpoints/internal_user_endpoints.py b/litellm/proxy/management_endpoints/internal_user_endpoints.py index ba7a3309a90..bf81e4eeb8d 100644 --- a/litellm/proxy/management_endpoints/internal_user_endpoints.py +++ b/litellm/proxy/management_endpoints/internal_user_endpoints.py @@ -2140,6 +2140,9 @@ async def get_users( user_ids: str | None = fastapi.Query(default=None, description="Get list of users by user_ids"), sso_user_ids: str | None = fastapi.Query(default=None, description="Get list of users by sso_user_id"), user_email: str | None = fastapi.Query(default=None, description="Filter users by partial email match"), + user_alias: str | None = fastapi.Query( + default=None, description="Filter users by partial alias match (case-insensitive)" + ), search: str | None = fastapi.Query( default=None, description="Combined search: matches users whose 'user_id' or 'user_email' contains the value (case-insensitive).", @@ -2174,6 +2177,8 @@ async def get_users( Get list of users by sso_ids. Comma separated list of sso_ids. user_email: Optional[str] Filter users by partial email match + user_alias: Optional[str] + Filter users by partial alias match (case-insensitive) search: Optional[str] Combined search: matches users whose user_id or user_email contains the value (case-insensitive) team: Optional[str] @@ -2235,6 +2240,9 @@ async def get_users( "mode": "insensitive", # Case-insensitive search } + if user_alias: + where_conditions["user_alias"] = {"contains": user_alias, "mode": "insensitive"} + if team is not None and isinstance(team, str): where_conditions["teams"] = { "has": team # Array contains for string arrays in Prisma diff --git a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py index 0d8b19345f1..431d69ba218 100644 --- a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py +++ b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py @@ -2078,6 +2078,71 @@ def test_get_users_search_matches_user_id_or_email(mocker): app.dependency_overrides.pop(user_api_key_auth, None) +def test_get_users_filters_by_partial_user_alias(mocker): + """ + `user_alias` filters rows and the total by a case-insensitive contains match, composes with other + filters, and an empty value applies no alias filter (a contains-"" match would drop users without an alias). + """ + from litellm.proxy._types import UserAPIKeyAuth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + aliased_user_id = "user-with-alias" + mock_user_row = mocker.MagicMock() + mock_user_row.user_id = aliased_user_id + mock_user_row.model_dump.return_value = { + "user_id": aliased_user_id, + "user_alias": "Jane Doe (Platform Team)", + "user_role": "internal_user", + "created_at": datetime.now(timezone.utc), + "updated_at": datetime.now(timezone.utc), + } + find_many_wheres = [] + count_wheres = [] + + async def mock_find_many(*args, **kwargs): + find_many_wheres.append(kwargs["where"]) + return [mock_user_row] + + async def mock_count(*args, **kwargs): + count_wheres.append(kwargs["where"]) + return 1 + + async def mock_key_count(*args, **kwargs): + return 0 + + mock_prisma_client = mocker.MagicMock() + mock_prisma_client.db.litellm_usertable.find_many = mock_find_many + mock_prisma_client.db.litellm_usertable.count = mock_count + mock_prisma_client.db.litellm_verificationtoken.count = mock_key_count + mocker.patch( # test-quality-ok: /user/list reads prisma_client off proxy_server at call time + "litellm.proxy.proxy_server.prisma_client", mock_prisma_client + ) + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN + ) + try: + alias_response = client.get("/user/list", params={"user_alias": "jane DOE"}) + assert alias_response.status_code == 200, alias_response.text + alias_where = {"user_alias": {"contains": "jane DOE", "mode": "insensitive"}} + assert find_many_wheres == [alias_where] + assert count_wheres == [alias_where] + assert [user["user_id"] for user in alias_response.json()["users"]] == [aliased_user_id] + assert alias_response.json()["total"] == 1 + + combined_response = client.get("/user/list", params={"user_alias": "jane", "role": "internal_user"}) + assert combined_response.status_code == 200, combined_response.text + assert find_many_wheres[-1] == { + "user_role": "internal_user", + "user_alias": {"contains": "jane", "mode": "insensitive"}, + } + + empty_response = client.get("/user/list", params={"user_alias": ""}) + assert empty_response.status_code == 200, empty_response.text + assert find_many_wheres[-1] == {} + finally: + app.dependency_overrides.pop(user_api_key_auth, None) + + def test_update_internal_user_params_reset_max_budget_with_none(): """ Test that _update_internal_user_params allows setting max_budget to None. diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts index 872875cc535..677287f70ae 100644 --- a/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -16935,6 +16935,8 @@ export interface paths { * Get list of users by sso_ids. Comma separated list of sso_ids. * user_email: Optional[str] * Filter users by partial email match + * user_alias: Optional[str] + * Filter users by partial alias match (case-insensitive) * search: Optional[str] * Combined search: matches users whose user_id or user_email contains the value (case-insensitive) * team: Optional[str] @@ -62062,6 +62064,8 @@ export interface operations { sso_user_ids?: string | null; /** @description Filter users by partial email match */ user_email?: string | null; + /** @description Filter users by partial alias match (case-insensitive) */ + user_alias?: string | null; /** @description Combined search: matches users whose 'user_id' or 'user_email' contains the value (case-insensitive). */ search?: string | null; /** @description Filter users by team id */ From 25505367f1349902e989eebb81c04d173a142d80 Mon Sep 17 00:00:00 2001 From: HARSHAVARDHAN-RAJU5 Date: Thu, 17 Sep 2026 22:45:26 +0530 Subject: [PATCH 2/3] refactor(proxy): build the /user/list alias filter without dict mutation The type-discipline gate (LIT002) rejected assigning the alias condition into where_conditions. Build it as a UserAliasWhere TypedDict in _user_alias_where and merge it into the final where, the same way the search filter already works. Behavior is unchanged. --- .../internal_user_endpoints.py | 18 ++++++++++++++---- .../internal_user_endpoints.py | 6 ++++++ 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/litellm/proxy/management_endpoints/internal_user_endpoints.py b/litellm/proxy/management_endpoints/internal_user_endpoints.py index bf81e4eeb8d..4855ebfdc3d 100644 --- a/litellm/proxy/management_endpoints/internal_user_endpoints.py +++ b/litellm/proxy/management_endpoints/internal_user_endpoints.py @@ -79,6 +79,7 @@ from litellm.types.proxy.management_endpoints.common_daily_activity import ( from litellm.types.proxy.management_endpoints.internal_user_endpoints import ( BulkUpdateUserRequest, BulkUpdateUserResponse, + UserAliasWhere, UserListResponse, UserSearchWhere, UserUpdateResult, @@ -2129,6 +2130,14 @@ def _user_search_where(search: str | None) -> Mapping[str, object]: return search_where +def _user_alias_where(user_alias: str | None) -> Mapping[str, object]: + """Prisma predicate for `/user/list?user_alias=`; empty is no filter, since contains "" drops NULL aliases.""" + if not user_alias: + return _NO_SEARCH_WHERE + alias_where: Final[UserAliasWhere] = {"user_alias": {"contains": user_alias, "mode": "insensitive"}} + return alias_where + + @router.get( "/user/list", tags=["Internal User management"], @@ -2240,9 +2249,6 @@ async def get_users( "mode": "insensitive", # Case-insensitive search } - if user_alias: - where_conditions["user_alias"] = {"contains": user_alias, "mode": "insensitive"} - if team is not None and isinstance(team, str): where_conditions["teams"] = { "has": team # Array contains for string arrays in Prisma @@ -2262,7 +2268,11 @@ async def get_users( ## Filter any none fastapi.Query params - e.g. where_conditions: {'user_email': {'contains': Query(None), 'mode': 'insensitive'}, 'teams': {'has': Query(None)}} where: Final[Mapping[str, object]] = { key: value - for key, value in (*where_conditions.items(), *_user_search_where(search).items()) + for key, value in ( + *where_conditions.items(), + *_user_alias_where(user_alias).items(), + *_user_search_where(search).items(), + ) if value is not None } diff --git a/litellm/types/proxy/management_endpoints/internal_user_endpoints.py b/litellm/types/proxy/management_endpoints/internal_user_endpoints.py index 43e3899d523..891c822fc40 100644 --- a/litellm/types/proxy/management_endpoints/internal_user_endpoints.py +++ b/litellm/types/proxy/management_endpoints/internal_user_endpoints.py @@ -28,6 +28,12 @@ class UserSearchWhere(TypedDict): OR: ReadOnly[tuple[Mapping[Literal["user_id", "user_email"], InsensitiveContains], ...]] +class UserAliasWhere(TypedDict): + """Prisma filter behind `/user/list?user_alias=`: user_alias contains the term, case-insensitive.""" + + user_alias: ReadOnly[InsensitiveContains] + + class UserListResponse(BaseModel): """ Response model for the user list endpoint From 1272a9dcc66209be7a164968494e19f4b3005905 Mon Sep 17 00:00:00 2001 From: HARSHAVARDHAN-RAJU5 Date: Fri, 18 Sep 2026 12:31:43 +0530 Subject: [PATCH 3/3] test(proxy): record /user/list alias calls with mocks instead of lists Greptile flagged the accumulator lists and the untyped *args/**kwargs callbacks in the new test against CLAUDE.md. Assert on AsyncMock call_args instead, so nothing is appended and no untyped callback is declared. Same three behaviors are covered. --- .../test_internal_user_endpoints.py | 40 +++++++------------ 1 file changed, 14 insertions(+), 26 deletions(-) diff --git a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py index 431d69ba218..8d6e0f4b396 100644 --- a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py +++ b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py @@ -2096,24 +2096,12 @@ def test_get_users_filters_by_partial_user_alias(mocker): "created_at": datetime.now(timezone.utc), "updated_at": datetime.now(timezone.utc), } - find_many_wheres = [] - count_wheres = [] - - async def mock_find_many(*args, **kwargs): - find_many_wheres.append(kwargs["where"]) - return [mock_user_row] - - async def mock_count(*args, **kwargs): - count_wheres.append(kwargs["where"]) - return 1 - - async def mock_key_count(*args, **kwargs): - return 0 - mock_prisma_client = mocker.MagicMock() - mock_prisma_client.db.litellm_usertable.find_many = mock_find_many - mock_prisma_client.db.litellm_usertable.count = mock_count - mock_prisma_client.db.litellm_verificationtoken.count = mock_key_count + find_many: Final = mocker.AsyncMock(return_value=[mock_user_row]) + count: Final = mocker.AsyncMock(return_value=1) + mock_prisma_client.db.litellm_usertable.find_many = find_many + mock_prisma_client.db.litellm_usertable.count = count + mock_prisma_client.db.litellm_verificationtoken.count = mocker.AsyncMock(return_value=0) mocker.patch( # test-quality-ok: /user/list reads prisma_client off proxy_server at call time "litellm.proxy.proxy_server.prisma_client", mock_prisma_client ) @@ -2121,24 +2109,24 @@ def test_get_users_filters_by_partial_user_alias(mocker): user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN ) try: - alias_response = client.get("/user/list", params={"user_alias": "jane DOE"}) + alias_response: Final = client.get("/user/list", params={"user_alias": "jane DOE"}) assert alias_response.status_code == 200, alias_response.text - alias_where = {"user_alias": {"contains": "jane DOE", "mode": "insensitive"}} - assert find_many_wheres == [alias_where] - assert count_wheres == [alias_where] - assert [user["user_id"] for user in alias_response.json()["users"]] == [aliased_user_id] + alias_where: Final = {"user_alias": {"contains": "jane DOE", "mode": "insensitive"}} + assert find_many.call_args.kwargs["where"] == alias_where + assert count.call_args.kwargs["where"] == alias_where + assert tuple(user["user_id"] for user in alias_response.json()["users"]) == (aliased_user_id,) assert alias_response.json()["total"] == 1 - combined_response = client.get("/user/list", params={"user_alias": "jane", "role": "internal_user"}) + combined_response: Final = client.get("/user/list", params={"user_alias": "jane", "role": "internal_user"}) assert combined_response.status_code == 200, combined_response.text - assert find_many_wheres[-1] == { + assert find_many.call_args.kwargs["where"] == { "user_role": "internal_user", "user_alias": {"contains": "jane", "mode": "insensitive"}, } - empty_response = client.get("/user/list", params={"user_alias": ""}) + empty_response: Final = client.get("/user/list", params={"user_alias": ""}) assert empty_response.status_code == 200, empty_response.text - assert find_many_wheres[-1] == {} + assert find_many.call_args.kwargs["where"] == {} finally: app.dependency_overrides.pop(user_api_key_auth, None)