perf: optimize user_api_key_auth

[ryan-crabbe]

Relevant issues

Pre-Submission checklist

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

• I have Added testing in the tests/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

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: https://app.circleci.com/pipelines/github/BerriAI/litellm/59051/workflows/82beffc6-7011-4b14-8892-003cb1e68d37

• CI run for the last commit
  Link: https://app.circleci.com/pipelines/github/BerriAI/litellm/59053/workflows/38110fb9-1e10-4d8c-ae3c-2e368d96aa19

• Merge / cherry-pick CI run
  Links:

Type

🐛 Bug Fix
🧹 Refactoring
✅ Test
Performance

Changes

On a request:

user_api_key_auth was computing the route by calling get_request_route(request) and then right after _user_api_key_auth_builder was callingget_request_route(request) again, throwing time away. The fix for this was getting the route one time and passing it to the auth builder to not have to figure it out again.

get_api_key was looping through pass-through endpoints, even though what was being hit during proxy vs provider benchmark was a /chat/completions request with a bearer token, and then a couple lines later check_api_key_for_custom_headers_or_pass_through_endpoints was being called which made this work redundant.

The fix for this was removing the redundant branch of get_api_key that was doing all that pass through endpoint checking and then leaving check_api_key_for_custom_headers_or_pass_through_endpoints to do that. And then also within check_api_key_for_custom_headers_or_pass_through_endpoints this was optimized to just check that the route starts with one of the pass through prefixes to begin with and that pass_through_endpoints isn't None (the config pass through endpoints that were set).

side note: The old pass through endpoints helper had an isinstance(request.headers, dict) guard before extracting custom headers for configured pass-through endpoints. Starlette's request.headers is a Headers object, not a dict, so this check was always False

Also cached public routes at the module level so its assigned at import time Cached request headers on every request to not have to create a dictionary of them a bunch of times.

Added regression tests as well for these changes.

Overall, this was a 10% improvement in UserAPIKeyAuth, but the most expensive part of this is construction of the AuthUserAPIKey object but I think this is because of line profiler overhead and the object having a lot of None values (tested the speed of constructing this object with a timer outside of the proxy server (with model construct and just init) so not sure.

Before

After

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Error		Feb 22, 2026 0:07am

[greptile-apps]

Greptile Summary

Performance optimizations to user_api_key_auth on the critical request path, achieving ~10% improvement by eliminating redundant work: computing the route once instead of twice, caching request headers per-request via request.state, pre-computing public routes and pass-through prefixes at module level, and adding fast-path early returns. Also fixes a latent bug where isinstance(request.headers, dict) was always False (Starlette headers are a Headers object), which silently prevented custom header-based API key extraction for authenticated pass-through endpoints.

• Eliminates redundant get_request_route() call by passing pre-computed route from user_api_key_auth into _user_api_key_auth_builder
• Caches dict(request.headers) on request.state._cached_headers to avoid repeated dict construction
• Pre-computes _PUBLIC_ROUTES and MAPPED_PASS_THROUGH_PREFIXES as module-level constants
• Removes redundant pass-through endpoint loop from get_api_key (handled by downstream check_api_key_for_custom_headers_or_pass_through_endpoints)
• Adds fast-path early return in check_api_key_for_custom_headers_or_pass_through_endpoints when route is not a pass-through route
• Note: route_checks.py changes semantics from substring match (in) to prefix match (startswith) for pass-through route detection — likely correct but worth verifying no routes rely on the old substring behavior
• Fixes the isinstance(request.headers, dict) guard that was always False, enabling custom header API key extraction for pass-through endpoints with auth enabled

Confidence Score: 4/5

• This PR is safe to merge — the optimizations are well-targeted and the one behavioral change (substring to prefix match) is practically correct for all known routes.
• The optimizations are clean, well-tested, and correctly preserve existing behavior in all but one spot: the route_checks.py change from substring (in) to prefix (startswith) matching is a subtle semantic change. While all known pass-through routes use these as prefixes, this should be acknowledged as intentional. The isinstance(request.headers, dict) fix is a genuine bug fix. Header caching is safe since all callers are read-only. Test coverage is good with 7 regression tests.
• Pay close attention to litellm/proxy/auth/route_checks.py — the in to startswith change alters route matching semantics.

Important Files Changed

Filename	Overview
litellm/proxy/auth/user_api_key_auth.py	Core performance optimizations: passes pre-computed route to _user_api_key_auth_builder, caches public routes at module level, uses _safe_get_request_headers (cached) instead of dict(request.headers), adds fast-path early return in check_api_key_for_custom_headers_or_pass_through_endpoints, removes redundant pass-through elif from get_api_key, fixes dead-code isinstance(request.headers, dict) guard, and adds break on matching endpoint.
litellm/proxy/_types.py	Adds MAPPED_PASS_THROUGH_PREFIXES as a pre-computed tuple constant from LiteLLMRoutes.mapped_pass_through_routes.value for use with str.startswith(). Clean, minimal change.
litellm/proxy/auth/route_checks.py	Replaces loop with route.startswith(MAPPED_PASS_THROUGH_PREFIXES) but changes semantics from substring match (in) to prefix match (startswith), which could affect routes where the pass-through prefix appears as a non-prefix substring.
litellm/proxy/common_utils/http_parsing_utils.py	Adds per-request caching for _safe_get_request_headers via request.state._cached_headers. All existing callers are read-only, making this safe. Includes proper fallback if request.state is unavailable.
litellm/proxy/pass_through_endpoints/pass_through_endpoints.py	Replaces loop with route.startswith(MAPPED_PASS_THROUGH_PREFIXES) — this location already used startswith in its loop, so this is a pure performance optimization with no behavioral change.
tests/test_litellm/proxy/auth/test_user_api_key_auth.py	Comprehensive regression tests covering: normal routes, mapped pass-through with header, configured endpoints (auth disabled, langfuse parser, custom headers), removal of get_api_key pass-through elif branch, and header caching. All tests use mocks (no network calls).
tests/test_litellm/proxy/common_utils/test_http_parsing_utils.py	Adds State() objects to existing test mocks so that the new header caching in _safe_get_request_headers works correctly — necessary fixup for the caching change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Incoming Request] --> B[user_api_key_auth]
    B --> C["get_request_route() - computed ONCE"]
    C --> D[_user_api_key_auth_builder with pre-computed route]
    D --> E[get_api_key - pass-through elif removed]
    E --> F["_safe_get_request_headers - cached on request.state"]
    F --> G{"route in _PUBLIC_ROUTES?<br/>(module-level set)"}
    G -- Yes --> H[Return public route auth]
    G -- No --> I[check_pass_through_endpoints]
    I --> J{"is_mapped = startswith(PREFIXES)?"}
    J -- "No + no config" --> K[Fast path: return api_key]
    J -- "Yes" --> L[Extract key from header]
    L --> M[Continue auth flow]
    K --> M
    I --> N{"Configured endpoint match?"}
    N -- "auth disabled" --> O[Return UserAPIKeyAuth]
    N -- "langfuse" --> P[Base64 decode key]
    N -- "custom header" --> Q["Extract from headers - isinstance bug fixed"]
    P --> M
    Q --> M
    O --> M

Loading

_{Last reviewed commit: c7ad805}

[greptile-apps]

_{6 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

auth: False check may miss falsy values

The condition endpoint.get("auth") is not True will pass for endpoints where auth is explicitly set to False, but it will also pass for endpoints that don't have an auth key at all (returns None), or where auth is any other truthy value like "yes".

Note: this is not a regression - the original code had the same check (endpoint.get("auth") is not True). Just flagging that if someone configures "auth": "enabled" on a pass-through endpoint, it would skip auth entirely since "enabled" is not True evaluates to True.

[greptile-apps]

New route parameter should be typed Optional[str]

The route parameter defaults to None, but the type annotation uses Optional[str] correctly. However, there's no docstring update to explain that callers can now pass in a pre-computed route to avoid redundant get_request_route() calls. A brief inline comment would help future maintainers understand this optimization.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[ryan-crabbe]

@greptileai re review

[greptile-apps]

_{7 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Subtle behavioral change: startswith vs in

The old code used if _llm_passthrough_route in route (substring match), but the new code uses route.startswith(MAPPED_PASS_THROUGH_PREFIXES) (prefix match). This is a semantic change: the old logic would match routes like /some/path/openai/endpoint where the prefix appears as a substring, while the new logic only matches routes that begin with the prefix.

In practice this is likely the correct behavior (all pass-through routes are defined with these as path prefixes), and the in check was overly broad. However, it should be intentional — if any routes exist where /openai, /anthropic, etc. appear as a non-prefix substring, they would no longer be classified as LLM API routes by _is_llm_api_route.