Support multiple headers mapped to the customer user role

[brtydse100]

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/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

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:

Type

🆕 New Feature
🐛 Bug Fix
🧹 Refactoring
📖 Documentation
🚄 Infrastructure
✅ Test

Changes

Added support for mapping multiple request headers to the same LiteLLM user role

general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
user_header_mappings:
- header_name: X-OpenWebUI-User-Id
litellm_user_role: internal_user
- header_name: X-OpenWebUI-User-Email
litellm_user_role: customer
- header_name: X-User-Id
litellm_user_role: customer

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Mar 15, 2026 8:21am

[greptile-apps]

Greptile Summary

This PR extends the user_header_mappings feature so that multiple request headers can share the customer user role, with the first matching header (in config declaration order) winning. get_customer_user_header_from_mapping now returns a lowercased list of header names instead of a single str, and get_end_user_id_from_request_body gains a new isinstance(list) branch that builds a case-insensitive lookup dict and iterates over the config list to honour priority. The deprecated user_header_name string path is preserved intact in the elif str branch with correct two-sided .lower() comparison.

Key changes:

• get_customer_user_header_from_mapping return type widened to Optional[list]; headers are lowercased at collection time to enable fast dict lookup later.
• New isinstance(list) branch iterates over the config list first (not over request headers), correctly enforcing config-declared priority rather than HTTP request ordering.
• Existing local_testing assertion updated to reflect the new list return type.
• Eight new unit tests added covering the multi-header path, single-header path, no-customer-role path, and the deprecated user_header_name fallback.
• One test coverage gap: no test exercises the scenario where the first customer-role header in the config list is absent from the request but a subsequent one is present.

Confidence Score: 4/5

• Safe to merge; core logic is correct and backward-compatible, with a minor test-coverage gap.
• The implementation correctly handles config-ordered priority, case-insensitive matching, and preservation of the deprecated string path. All previously flagged issues (priority order, case sensitivity, missing deprecated-path test) appear addressed in the HEAD commit. The only remaining gap is the absence of a test for the "first customer header absent, second present" fallback scenario within the list path — a realistic use-case that the code handles correctly but no test would catch if it regressed.
• No files require special attention; the minor coverage gap is in tests/test_litellm/proxy/auth/test_auth_utils.py.

Important Files Changed

Filename	Overview
litellm/proxy/auth/auth_utils.py	Changed get_customer_user_header_from_mapping to return Optional[list] (lowercased names) instead of Optional[str], and updated get_end_user_id_from_request_body to handle the new list path with correct config-priority iteration. Deprecated user_header_name string path preserved with correct case-insensitive comparison on both sides.
tests/test_litellm/proxy/auth/test_auth_utils.py	New tests added for the multi-header customer role feature, including config-order priority and deprecated fallback. Missing a test for the "first config header absent, second present" fallback scenario.
tests/local_testing/test_auth_utils.py	Existing test updated to reflect that get_customer_user_header_from_mapping now returns a lowercased list instead of a single string; no new concerns.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[get_end_user_id_from_request_body] --> B[_get_customer_id_from_standard_headers]
    B -->|found| Z[Return customer ID]
    B -->|None| C{user_header_mappings configured?}
    C -->|Yes| D[get_customer_user_header_from_mapping]
    D --> E{Any customer-role\nheaders?}
    E -->|Yes| F["Return list of lowercased\nheader names (config order)"]
    E -->|No| G[Return None]
    F --> H[custom_header_name_to_check = list]
    G --> I{user_header_name\nconfigured?}
    C -->|No| I
    I -->|Yes| J[custom_header_name_to_check = str]
    I -->|No| K[custom_header_name_to_check = None]
    H --> L{isinstance list?}
    J --> L
    K --> L
    L -->|list| M[Build headers_lower dict\nlowercase keys]
    M --> N[Iterate config list in order]
    N --> O{Header in request?}
    O -->|Yes, non-empty| Z
    O -->|No / empty| P{More headers\nin config?}
    P -->|Yes| N
    P -->|No| Q[Fall through to request body]
    L -->|str| R[Iterate request headers\ncase-insensitive compare]
    R --> O2{Match found\nand non-empty?}
    O2 -->|Yes| Z
    O2 -->|No| Q
    L -->|None| Q
    Q --> S{user field in\nrequest body?}
    S -->|Yes| Z
    S -->|No| T[Return None]

Loading

Comments Outside Diff (1)

1. tests/test_litellm/proxy/auth/test_auth_utils.py, line 271-289 (link)

   Missing test: first header absent, second present in config list

   test_get_end_user_id_returns_first_customer_header_when_multiple_mappings_exist only covers the case where the first config-ordered customer header is present in the request. There is no test verifying that the code correctly falls back to the next customer header in config order when the first is absent from the request. For example:

   • Config order: ["x-user-id", "x-openwebui-user-email"]
   • Request contains only x-openwebui-user-email, not x-user-id

   The expected result is "user@example.com", which the current implementation would produce correctly (because it iterates over the config list), but a regression here would go undetected. Adding this case would meaningfully improve coverage of the new multi-header fallback feature.

_{Last reviewed commit: a4db364}

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing brtydse100:feat/same_role_multiple_headers_mapping (a4db364) with main (548e7eb)}