fix(proxy): make common_checks opt-in for custom auth

[Harshit28j]

Summary

Replaces the skip_route_check approach from PR #22662 with a configurable opt-in
By default, common_checks() is not run for custom auth flows, preserving backwards compatibility with pre-#22164 behavior. Users who want budget/team/route enforcement on custom auth can explicitly opt in:

general_settings:
  custom_auth: my_auth.user_api_key_auth
  custom_auth_run_common_checks: true

Changes

• Reverts fix(proxy): allow custom auth routes to bypass route authorization ch… #22662 skip_route_check parameter from common_checks() in auth_checks.py
• Wraps the common_checks() call in _run_post_custom_auth_checks() behind general_settings.get("custom_auth_run_common_checks", False)
• Updates existing tests and adds new test verifying opt-in behavior

Pre-Submission checklist

• I have Added testing in the tests/litellm/ directory
• My PR passes all unit tests
• My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

🐛 Bug Fix

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Error		Mar 3, 2026 5:21pm

[greptile-apps]

Greptile Summary

This PR replaces the skip_route_check parameter approach (from PR #22662) with a cleaner opt-in flag custom_auth_run_common_checks in general_settings. By default, common_checks() is not run for custom auth flows, restoring backwards compatibility broken by PR #22164. Users who want budget/team/route enforcement on custom auth can explicitly enable it. This directly addresses the custom rule requiring user-controlled flags for backwards-incompatible changes.

• Reverted skip_route_check parameter from common_checks() in auth_checks.py, restoring unconditional route checking for non-custom-auth paths
• Gated the common_checks() call in _run_post_custom_auth_checks() behind general_settings.get("custom_auth_run_common_checks", False)
• Updated and added tests verifying both the default (skipped) and opt-in (enabled) behavior
• Fixed unrelated guardrails documentation: corrected JSON syntax ([] → {} for per-guardrail config) and removed duplicate closing braces in curl examples

Confidence Score: 4/5

• This PR is safe to merge — it restores backwards compatibility for custom auth users and adds a clean opt-in mechanism.
• Score of 4 reflects a well-scoped fix that directly addresses a backwards-compatibility regression with proper feature flagging, good test coverage for both paths, and clean revert of the previous approach. Deducted 1 point because the docs changes are unrelated to the main fix and could be split into a separate PR for cleaner history.
• No files require special attention. The core logic change in user_api_key_auth.py is minimal and well-tested.

Important Files Changed

Filename	Overview
litellm/proxy/auth/auth_checks.py	Reverts skip_route_check parameter from common_checks(), restoring the unconditional route check. Clean removal with no remaining references.
litellm/proxy/auth/user_api_key_auth.py	Wraps common_checks() call in _run_post_custom_auth_checks() behind general_settings.get("custom_auth_run_common_checks", False) opt-in flag, preserving backwards compatibility.
tests/test_litellm/proxy/auth/test_auth_checks.py	Rewrites test to verify opt-in behavior of _run_post_custom_auth_checks with mock-only approach. Tests both default (skipped) and opt-in (called) paths.
tests/test_litellm/proxy/auth/test_custom_auth_end_user_budget.py	Adds assertions verifying common_checks is not awaited by default and adds new test case for the opt-in flag enabling common_checks.
docs/my-website/docs/proxy/guardrails/quick_start.md	Fixes guardrails doc examples: changes [] to {} for per-guardrail config syntax, and removes duplicate closing braces in curl examples. Unrelated to the main auth change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Custom Auth returns UserAPIKeyAuth] --> B["_run_post_custom_auth_checks()"]
    B --> C{end_user_id set?}
    C -->|Yes| D[Lookup end_user + apply budget]
    C -->|No| E[Skip end_user lookup]
    D --> F[Key expiry + model budget checks]
    E --> F
    F --> G{custom_auth_run_common_checks?}
    G -->|"True (opt-in)"| H["common_checks() — route, budget, team, guardrails"]
    G -->|"False (default)"| I[Skip common_checks]
    H --> J[Return valid_token]
    I --> J

Loading

_{Last reviewed commit: a6b57f9}