fix(auth): name enable_jwt_auth when a JWT-shaped key is rejected

[yassin-berriai]

TLDR

Problem this solves:

• A JWT sent without enable_jwt_auth is reported as a bad virtual key
• The error names no config, so operators go debug virtual keys
• The unlicensed JWT gate answers 401, inviting an endless retry

How it solves it:

• Append a hint naming general_settings.enable_jwt_auth to that rejection
• Only for keys that are actually three-segment JWTs
• Raise 403 from the enterprise gate, matching every sibling gate

Relevant issues

Linear ticket

Resolves LIT-5166

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

Postgres-backed proxy on a namespaced port, LITELLM_LICENSE exported empty so the install is unlicensed, and a real RS256 JWT with a kid header minted for the run. Before runs captured at ad79b314c5, after runs at ffad9185b7

Case 1 uses a general_settings block that sets JWT_PUBLIC_KEY_URL in the environment and omits enable_jwt_auth, which is the configuration mistake this fixes

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: sk-lit5171-master

curl -sS -i -X POST http://127.0.0.1:4171/v1/chat/completions \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Before, at ad79b314c5

HTTP/1.1 401 Unauthorized
{"error":{"message":"LiteLLM Virtual Key expected. Received=eyJh****vuRw, expected to start with 'sk-'.","type":"auth_error","param":"None","code":"401"}}

After, at ffad9185b7

HTTP/1.1 401 Unauthorized
{"error":{"message":"LiteLLM Virtual Key expected. Received=eyJh****vuRw, expected to start with 'sk-'. This key has the structure of a JWT, but JWT auth is not enabled on this proxy, so it was treated as a virtual key. Set `enable_jwt_auth: true` under `general_settings` in your proxy config to authenticate with JWTs.","type":"auth_error","param":"None","code":"401"}}

The same config and the same build, with an opaque key instead of a JWT-shaped one, showing the hint is scoped rather than appended to every rejection

curl -sS -i -X POST http://127.0.0.1:4171/v1/chat/completions \
  -H "Authorization: Bearer not-a-jwt-at-all" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

HTTP/1.1 401 Unauthorized
{"error":{"message":"LiteLLM Virtual Key expected. Received=not-****-all, expected to start with 'sk-'.","type":"auth_error","param":"None","code":"401"}}

Case 2 adds enable_jwt_auth: True to the same config, still unlicensed, same curl

Before, at ad79b314c5

HTTP/1.1 401 Unauthorized
{"error":{"message":"Authentication Error, JWT Auth is an enterprise only feature. You must be a LiteLLM Enterprise user to use this feature. If you have a license please set `LITELLM_LICENSE` in your env. Get a 7 day trial key here: https://www.litellm.ai/enterprise#trial. \nPricing: https://www.litellm.ai/#pricing","type":"auth_error","param":"None","code":"401"}}

After, at ffad9185b7

HTTP/1.1 403 Forbidden
{"error":{"message":"JWT Auth is an enterprise only feature. You must be a LiteLLM Enterprise user to use this feature. If you have a license please set `LITELLM_LICENSE` in your env. Get a 7 day trial key here: https://www.litellm.ai/enterprise#trial. \nPricing: https://www.litellm.ai/#pricing","type":"auth_error","param":"premium_user","code":"403"}}

The Authentication Error, prefix drops because it belonged to the terminal catch-all; a ProxyException passes through the handler unmodified

Control on the fixed build, showing an ordinary virtual key still authenticates and reaches the real OpenAI API at real cost, at ffad9185b7

KEY=$(curl -sS -X POST http://127.0.0.1:4171/key/generate \
  -H "Authorization: Bearer sk-lit5171-master" -H "Content-Type: application/json" \
  -d '{"models":["gpt-4o-mini"]}' | python -c "import sys,json;print(json.load(sys.stdin)['key'])")
curl -sS -i -X POST http://127.0.0.1:4171/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Say OK"}]}'

HTTP/1.1 200 OK
{"id":"chatcmpl-E9GunUjPPrIYA6ngZG5lA7EQc6Tzm","created":1785878681,"model":"gpt-4o-mini","object":"chat.completion","choices":[{"finish_reason":"stop","index":0,"message":{"content":"OK!","role":"assistant"}}], ...}

Type

🐛 Bug Fix

Changes

general_settings.enable_jwt_auth gates whether a token is even recognized as a JWT. With the flag unset, is_jwt is hardcoded to False, so a JWT falls through to the virtual-key path and is rejected by the sk- prefix guard for not looking like a virtual key. The docs list JWT_PUBLIC_KEY_URL first, so setting the env var and forgetting the config line is an easy mistake, and the resulting message sends the operator to inspect virtual keys for what is a one-line config problem

The rejection now appends a sentence naming enable_jwt_auth, and only when the presented key is three-segment. JWTHandler.is_jwt is a pure structural check with no side effects, so consulting it in that branch costs nothing and cannot change who authenticates. Note it is called explicitly rather than reusing the local is_jwt, which is pinned to False whenever the flag is off and would make the branch unreachable. Nothing beyond the already-masked key is added to the message

The hint claims only that the key has the structure of a JWT, never that it is one. Segment count cannot distinguish a JWT from any other dotted credential, so a message asserting the key IS a JWT would trade one confident misdiagnosis for a narrower one, which is the same failure this PR exists to fix. The classifier itself is deliberately left alone; is_jwt is litellm's definition of JWT-shaped everywhere else on this path, and applying a stricter rule in one branch would be an inconsistency for the next reader to trip over

The hint is appended rather than substituted because the existing text is matched elsewhere. PrometheusLogger._is_invalid_api_key_request substring-matches expected to start with 'sk-' to suppress metrics for invalid keys, so replacing that text would quietly distort an invalid-key metric instead of failing loudly. I checked the filter against the lengthened message directly and it still matches, and tests/test_litellm/integrations/test_prometheus_invalid_key_filtering.py passes unchanged

The second change is narrower and worth stating precisely, because the message on that path is not the problem. A client that sets the flag on an unlicensed install already receives "JWT Auth is an enterprise only feature. You must be a LiteLLM Enterprise user...", which says what is wrong. What is wrong is only the status code. The gate raised a bare ValueError, which the terminal handler in auth_exception_handler.py converts to a 401, while every sibling enterprise gate answers 403, including _premium_user_check and the SSO gate. A 401 tells a client its credential was wrong and to retry with a better one, and no credential can satisfy that while the install is unlicensed. It now raises a 403 ProxyException shaped like the SSO gate

One string delta comes with that status code change and is worth calling out so it does not read as an accident. The 401 body was prefixed "Authentication Error, " because the terminal catch-all builds that message itself out of str(e). A ProxyException is re-raised by the handler unmodified, so the 403 body carries the gate's own message without the prefix. The sentence naming the enterprise requirement is unchanged

On how much this is worth: a GitHub issue search turned up no other user reporting this specific symptom. The confusing-auth-error surface is well attested, in #18474 and #24680 among others, but those are virtual-key problems on a different code path. The case for this one rests on the code path itself and a single customer report, not on a pattern of reports

Authentication behavior is unchanged. No new config, no new environment variable, and every request that authenticated before still authenticates

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

[yassin-berriai]

@greptileai please review

[greptile-apps]

Greptile Summary

The PR clarifies rejected JWT-shaped credentials without definitively identifying them as JWTs and returns a structured 403 response when JWT authentication is enabled without an enterprise license.

• Adds a configuration hint only for rejected three-segment credentials when JWT authentication is disabled.
• Uses ProxyException to classify the unlicensed JWT gate as forbidden.
• Adds focused tests for hint scope, wording, and the enterprise-gate status.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
litellm/proxy/auth/user_api_key_auth.py	Adds qualified JWT-structure guidance and converts the unlicensed JWT gate to a handled 403 response; the prior definitive-diagnosis concern is resolved.
tests/test_litellm/proxy/auth/test_user_api_key_auth.py	Adds isolated tests covering qualified wording, non-JWT-shaped controls, preserved virtual-key text, and the unlicensed 403 response.

_{Reviews (2): Last reviewed commit: "fix(auth): name enable_jwt_auth when a J..." | Re-trigger Greptile}

[greptile-apps]

Three segments are labeled JWT

JWTHandler.is_jwt only checks for three dot-separated segments, so an unrelated value such as foo.bar.baz receives a definitive JWT diagnosis and directs operators to enable and license JWT authentication instead of correcting the malformed credential.

Knowledge Base Used: Proxy Authentication and Authorization

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yassin-berriai]

@greptileai re-review please. Fixed at ffad918: the hint no longer claims the key is a JWT, only that it has the structure of one, since segment count cannot tell a JWT from any other dotted credential. Classifier unchanged on purpose.

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_jwt_auth_disabled_error (ffad918) with litellm_internal_staging (e64536c)}