fix(auth): stop the team fallback from widening model access

[yassin-berriai]

TLDR

Problem this solves:

• A failed team lookup could grant models the team never allowed
• The same fallback also read an unresolvable team as unblocked

How it solves it:

• A team that is provably gone now refuses, with no override
• An unreadable team keeps the fallback, so nobody is locked out

User Flow

Before: a developer's team key keeps working after its team can no longer be resolved, and it now reaches models the team never allowed

1. Their proxy admin creates a team limited to gpt-4o-mini and issues them a key that inherits the team's models
2. They send POST https://litellm-domain/v1/chat/completions with "model": "gpt-4o-mini" and get a 200 with a completion
3. They send the same POST with "model": "gpt-4.1" and get a 403 reading team not allowed to access model. This team can only access models=['gpt-4o-mini']
4. Their team is later removed while the key survives
5. They send POST https://litellm-domain/v1/chat/completions with "model": "gpt-4.1" again and now get a 200 with a real gpt-4.1 completion
6. Anyone holding such a key can reach every model on the proxy, not only the ones their team was given

After: the same key stops at the point its team can no longer be resolved

1. Their proxy admin creates a team limited to gpt-4o-mini and issues them a key that inherits the team's models
2. They send POST https://litellm-domain/v1/chat/completions with "model": "gpt-4o-mini" and get a 200 with a completion
3. They send the same POST with "model": "gpt-4.1" and get a 403 reading team not allowed to access model. This team can only access models=['gpt-4o-mini']
4. Their team is later removed while the key survives
5. They send POST https://litellm-domain/v1/chat/completions with "model": "gpt-4.1" again and now get a 404 reading Team doesn't exist in db
6. Anyone holding such a key can no longer reach models their team was never given: the request is refused instead of upgraded

Relevant issues

Linear ticket

Resolves LIT-5522

Pre-Submission checklist

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

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

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

Screenshots / Proof of Fix

Live proxy against a real Postgres and real OpenAI calls. One setup serves every leg: a team restricted to gpt-4o-mini with a key that inherits the team's allowlist, which is what the Admin UI produces by default, so the team object is the only gate on model access

curl -s -X POST http://127.0.0.1:4552/team/new \
  -H 'Authorization: Bearer sk-lit5522-master' -H 'Content-Type: application/json' \
  -d '{"team_alias":"lit5522-restricted","models":["gpt-4o-mini"]}'
# {"team_alias":"lit5522-restricted","team_id":"a2c35cd9-...","models":["gpt-4o-mini"]}

curl -s -X POST http://127.0.0.1:4552/key/generate \
  -H 'Authorization: Bearer sk-lit5522-master' -H 'Content-Type: application/json' \
  -d '{"team_id":"a2c35cd9-...","models":[],"key_alias":"lit5522-teamkey"}'
# key.models = []   key.team_id = a2c35cd9-...

Every request below is the same shape, varying only the key and the model

curl -s -w '\nHTTP %{http_code}\n' http://127.0.0.1:4552/v1/chat/completions \
  -H "Authorization: Bearer $TEAM_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4.1","messages":[{"role":"user","content":"reply with the single word lit5522"}],"max_tokens":10}'

Three team states are exercised. HEALTHY is the ordinary case. GONE is a team removed while its key survives, which is also what a partial restore leaves behind. UNREADABLE is a team whose row is present but will not load, which is what a database fault looks like from here

Before, at commit 373a0fc506

HEALTHY,    gpt-4o-mini  -> HTTP 200  {"id":"chatcmpl-ECZGbkjwswHSgiPmNaFtmVZ7AgcBf","model":"gpt-4o-mini",...,"content":"lit5522"}
HEALTHY,    gpt-4.1      -> HTTP 403  team not allowed to access model. This team can only access models=['gpt-4o-mini']
GONE,       gpt-4.1      -> HTTP 200  {"id":"chatcmpl-ECZGcTjdpHdPIfMYo7E8DG8vRIuVY","model":"gpt-4.1",...,"content":"lit5522"}
UNREADABLE, gpt-4.1      -> HTTP 200  {"id":"chatcmpl-ECZGeptFfBzipVOBgMmdVdNkWJqLl","model":"gpt-4.1",...,"content":"lit5522"}

The control succeeds outright and the ungranted model is refused, so the allowlist is demonstrably in force before anything is disturbed. The proxy log records the decision rather than leaving it to be inferred from where the request landed

LiteLLM Proxy:DEBUG: user_api_key_auth.py - centralized auth: team fetch failed
(HTTPException: 404: {'error': "Team doesn't exist in db. Team=a2c35cd9-... Create team via `/team/new` call."})

After, at commit a45fbba01a

HEALTHY,    gpt-4o-mini  -> HTTP 200  {"id":"chatcmpl-ECZG5Slx1xBJkiXpwVs8Yqbsm9Wj8","model":"gpt-4o-mini",...,"content":"lit5522"}
HEALTHY,    gpt-4.1      -> HTTP 403  team not allowed to access model. This team can only access models=['gpt-4o-mini']
GONE,       gpt-4.1      -> HTTP 404  Team doesn't exist in db. Team=a2c35cd9-...
UNREADABLE, gpt-4.1      -> HTTP 404  Team doesn't exist in db. Team=5dc10382-...

The decisive pair, both with allow_requests_on_db_unavailable: true, same proxy and same request. A degraded read still serves, and a definitive answer still refuses

UNREADABLE, gpt-4.1, opt-in set -> HTTP 200  {"id":"chatcmpl-ECZFWlMXlWsofO7srFQOgmpx9s2Nr","model":"gpt-4.1",...,"content":"lit5522"}
GONE,       gpt-4.1, opt-in set -> HTTP 404  Team doesn't exist in db. Team=a2c35cd9-...

Type

🐛 Bug Fix

Review notes

Why the fix reaches into get_team_object rather than living entirely at the call site. That function reported a deleted team and a database that would not answer as the same 404, so the fallback had no way to tell a definitive answer from a degraded read. The first version of this PR tried to bound that with allow_requests_on_db_unavailable, which was wrong: that helper is () -> bool with no exception parameter, a static settings read, and every other caller in the tree pairs it with is_database_connection_error(e). Using only the static half meant an operator who set it for outages would also have handed a deleted team's key the permissive fallback with the database perfectly healthy, which is the case this PR exists to close. An earlier revision of this description published that as proof the opt-out worked, when it was demonstrating the hole, and the GONE leg with the opt-in set is its corrected counterpart. The subclass is what makes consulting the setting legitimate, because by the time it is read the failure is known to be a degraded read

Who this denies, stated plainly rather than left qualitative. The refusal keys on the token carrying no team model grant, and a genuinely unrestricted team also records models: [], which is byte-identical to no grant. So the population that loses access is a key under an unrestricted team, and only while that team's row will not load. Unrestricted is a common team shape rather than an edge case, so this is a wider set than "a deleted team": any team created without an explicit model list looks the same to this check. It costs them nothing while the database is healthy, because the row resolves and this code never runs, and allow_requests_on_db_unavailable restores the previous behaviour for exactly that case, as the UNREADABLE legs show

The full CI matrix is itself the best evidence that the closed case holds no real traffic. Two legacy tests failed, and they are the only two places in the repo that exercise the widening state, and only because their database is a stub, so their team lookup always fails. Both were repaired by giving their team key a model grant, which is the realistic shape of a team key: that changes the fixture's realism, not the test's meaning, and every assertion in them is untouched

Test isolation worth knowing about: both mapped test files call importlib.reload on auth_checks, which rebinds the exception class, so a test importing it from there and injecting it into a patched lookup raises a type the guard has never seen. The new call-site tests import it from the module under test instead. Verified by running both files in one session in both orderings

Mutation check, five mutants, each run separately with bytecode cleared and a nonzero test count each time. Downgrading the subclass at the raise site, and dropping its pass-through in get_team_object, each kill the discriminator test. Removing the absent-team guard at the call site kills both parametrized refusal cases. Making the token grant always vouch, and making the opt-out never apply, each kill their own case. The first of those mutants SURVIVED an earlier revision, which is what exposed that the call-site tests were injecting the exception rather than provoking it, so a test that drives the real lookup was added

One typing note so it does not read as an oversight: this adds a single reportUnknownMemberType from reading team_models, which is annotated as a bare list on the shared token model. The rule's codebase ceiling is 39237 and the gate fails only when a rule is both over its limit and above base, so this is well inside it. Tightening that annotation would have turned a security fix into a change to a shared model, which is the wrong trade here

Caveats (if any)

• A key whose team is provably gone is now refused outright
• An unreadable team still falls back, unless the token records no grant
• allow_requests_on_db_unavailable covers only the unreadable case

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Greptile Summary

This PR hardens team-resolution behavior in centralized proxy authorization while preserving a configured degraded-service path.

• Distinguishes a definitively absent team from an unreadable team.
• Conditions token-derived team fallback on the lookup outcome and recorded grant.
• Adds focused tests for absent, unreadable, restricted, and configured fallback states.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
litellm/proxy/auth/auth_checks.py	Introduces a distinct not-found exception so successful absence can be separated from lookup failures.
litellm/proxy/auth/user_api_key_auth.py	Restricts token-derived team fallback according to lookup outcome, token grant, and availability configuration.
tests/test_litellm/proxy/auth/test_auth_checks.py	Verifies that absent and unreadable team rows produce distinguishable exception types.
tests/test_litellm/proxy/auth/test_user_api_key_auth.py	Covers centralized authorization behavior for deleted teams, unreadable teams, and recorded model grants.
tests/proxy_unit_tests/test_user_api_key_auth.py	Updates existing fixtures to retain their intended non-fallback test paths under the stricter authorization behavior.

_{Reviews (4): Last reviewed commit: "fix(auth): stop the team fallback from w..." | Re-trigger Greptile}

[yassin-berriai]

@greptileai re-review at 0e04e4b, the verbose commentary finding is addressed and behavior is unchanged

[codecov]

Codecov Report

❌ Patch coverage is 94.73684% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/auth/user_api_key_auth.py	91.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[yassin-berriai]

@greptileai re-review at 7f2ae5e, adds two legacy fixture updates only; the source change is unchanged since your 5/5

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_lit5522_team_obj_fail_closed (a45fbba) with litellm_internal_staging (262ed53)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (373a0fc) during the generation of this report, so 262ed53 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[yassin-berriai]

@greptileai re-review at a45fbba, the availability opt-out no longer overrides a definitively deleted team; see Review notes