fix(proxy): single-team DB fallback when JWT has no team_id

[milan-berri]

Relevant issues

JWT calls with no team in the token left team_id unset even when the user existed in LiteLLM on a single team, so spend/metadata did not attach to that team. This change infers that team only when unambiguous (exactly one team on the user row).

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Screenshots / Proof of Fix

Manual verification: with enable_jwt_auth, JWT with only sub (no team claims), and a LiteLLM user in exactly one team, spend/metadata should show that team_id / user_api_key_team_id. With two teams on the user, no team is inferred (ambiguous). Unit tests in test_handle_jwt.py cover these cases with mocks (no real LLM calls).

Type

🆕 New Feature
✅ Test

Changes

• auth_builder (JWT): If team_id is still unset after the normal JWT/team resolution flow, and user_object.teams has exactly length 1, attempt to load that team via get_team_object and (when user_id is set) get_team_membership. Both calls are wrapped in a single try/except Exception — any error (including HTTPException(404) when the team row is missing, which is what get_team_object raises in production) is debug-logged and silently skipped; the request continues without a team_id. No new failure path is introduced. If the user has 0 or 2+ teams, the fallback is not attempted.
• Tests: Parametrized test_auth_builder_single_team_db_fallback_when_jwt_has_no_team — covers: single team resolves correctly; two teams / zero teams / get_team_object raising HTTPException(404) / get_team_object raising HTTPException(500) all leave team_id unset without failing auth. Added test_auth_builder_single_team_fallback_membership_error_skips_no_raise — get_team_object succeeds but get_team_membership raises, result has no team context and no exception.

[greptile-apps]

Greptile Summary

This PR adds a single-team DB fallback to JWTAuthManager.auth_builder: when a JWT token carries no team claim and the authenticated user belongs to exactly one team in LiteLLM's DB, the new _resolve_single_team_fallback helper fetches that team (and its membership) so spend/metadata can be attributed correctly. The previous P1 issues flagged in earlier review rounds are now resolved — get_team_object failures are caught by a broad try/except Exception, and the orphaned-team test case correctly uses side_effect = HTTPException(status_code=404) to match real behaviour.

Confidence Score: 5/5

Safe to merge; the previously flagged P1 issues are addressed and only a dead-code style nit remains.

Both P1 bugs from prior review rounds are fixed: the try/except Exception now properly swallows HTTPException(404) from get_team_object, and the test mock for the orphaned-team case now raises instead of returning None. The sole remaining finding is a P2 dead-code guard (if team_row is None) that is unreachable but harmless.

litellm/proxy/auth/handle_jwt.py — the unreachable if team_row is None guard in _resolve_single_team_fallback (line 1492)

Important Files Changed

Filename	Overview
litellm/proxy/auth/handle_jwt.py	Adds _resolve_single_team_fallback static method and wires it into auth_builder after team resolution; the try/except Exception correctly swallows HTTPException(404/500) from get_team_object, but the if team_row is None guard inside is dead code since that function never returns None.
tests/test_litellm/proxy/auth/test_handle_jwt.py	Adds parametrized tests for the single-team DB fallback; the one_team_id_but_row_missing_in_db case now correctly uses side_effect = HTTPException(status_code=404, ...) matching the real get_team_object behaviour, and a separate test covers the membership-error path.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[JWT auth_builder called] --> B[Resolve team_id from token/header/routing]
    B --> C{team_id resolved?}
    C -- Yes --> G[get_objects: user, org, end_user, membership]
    C -- No --> D[_resolve_single_team_fallback]
    D --> E{user_object.teams length == 1?}
    E -- No / 0 or 2+ teams --> F[return None, None, None]
    E -- Yes --> H[get_team_object team_id]
    H --> I{raises Exception?}
    I -- Yes --> J[debug log, return None, None, None]
    I -- No --> K{user_id set?}
    K -- No --> L[return team_id, team_row, None]
    K -- Yes --> M[get_team_membership]
    M --> N{raises Exception?}
    N -- Yes --> J
    N -- No --> O[return team_id, team_row, membership]
    F --> G
    L --> G
    O --> G
    J --> G
    G --> P[map_user_to_teams]
    P --> Q[validate_object_id]
    Q --> R[Return JWTAuthBuilderResult]

Loading

_{Reviews (5): Last reviewed commit: "refactor(jwt): extract single-team fallb..." | Re-trigger Greptile}

[veria-ai]

Low: No security issues found

This PR adds a single-team DB fallback in the JWT auth flow so that when a JWT token doesn't carry a team_id claim, but the authenticated user belongs to exactly one team in the database, that team is automatically associated. The fallback reads from the user's own trusted DB record (not attacker-controlled input), the team is validated via get_team_object, and all downstream authorization checks (budget, model access, RBAC) still apply. The removed scopes assignment was a duplicate — scopes is still correctly assigned and used for scope-based access checks and admin access checks.

---

Status: 0 open
Risk: 2/10

Posted by Veria AI · 2026-04-24T23:52:33.773Z

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/auth/handle_jwt.py	88.88%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[ishaan-berri]

@milan-berri no do not allow noqa: PLR0915 instead place this logic in it's own helper

[milan-berri]

addressed!