feat(sdk): add proxy_auth for auto OAuth2/JWT token management

[Chesars]

Relevant issues

Fixes #19834

Pre-Submission checklist

• 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

Type

🆕 New Feature

Changes

Adds litellm.proxy_auth to automatically obtain and refresh OAuth2/JWT tokens when connecting to LiteLLM Proxy or any OAuth2-protected endpoint.

Features:

• ProxyAuthHandler: Manages token lifecycle (obtain, cache, refresh with 60s buffer)
• AzureADCredential: Wrapper for azure-identity credentials (DefaultAzureCredential, ClientSecretCredential, etc.)
• GenericOAuth2Credential: Works with any OAuth2 provider (Okta, Auth0, Keycloak, etc.)
• TokenCredential Protocol: Users can implement custom credential providers

Usage:

import litellm
from litellm.proxy_auth import AzureADCredential, ProxyAuthHandler

# One-time setup
litellm.proxy_auth = ProxyAuthHandler(
    credential=AzureADCredential(),  # uses DefaultAzureCredential
    scope="api://my-litellm-proxy/.default"
)
litellm.api_base = "https://my-proxy.example.com"

# Auth headers are now automatically injected
response = litellm.completion(model="gpt-4", messages=[...])

Tests:

• 12 unit tests covering all credential providers and integration with litellm module
• All tests pass: poetry run pytest tests/litellm/test_proxy_auth.py -v

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 1, 2026 11:01pm

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds automatic OAuth2/JWT token management for authenticating with LiteLLM Proxy and other OAuth2-protected endpoints. The implementation introduces a new litellm.proxy_auth module with clean credential provider abstractions.

Key Changes:

• New ProxyAuthHandler class that manages token lifecycle (obtain, cache, refresh with 60s buffer)
• AzureADCredential wrapper for azure-identity credentials with lazy initialization
• GenericOAuth2Credential for standard OAuth2 client credentials flow
• Protocol-based design (TokenCredential) allows custom credential providers
• Auth headers automatically injected in completion() and embedding() methods
• Graceful error handling with warning logs if token fetch fails

Implementation Quality:

• Well-structured code with proper separation of concerns
• Token caching prevents unnecessary OAuth2 requests (performance-conscious)
• 60-second expiry buffer ensures tokens are refreshed before expiration
• Comprehensive unit tests (12 tests) covering all credential providers and edge cases
• No performance impact in the critical request path per custom instruction (auth object created once, not per request)

Confidence Score: 4/5

• This PR is safe to merge with minor considerations
• The implementation is well-designed with proper error handling, caching, and comprehensive tests. The code follows good patterns (Protocol-based design, lazy initialization, graceful degradation). Score is 4 instead of 5 because: (1) auth injection only covers completion() and embedding() methods - other API methods like text_completion(), transcription(), and speech() might also benefit from this feature if users call them through a proxy, though these are likely less commonly used, (2) no integration test demonstrating end-to-end usage with actual completion/embedding calls
• Pay attention to litellm/main.py - verify whether other API methods besides completion/embedding should also receive auth injection

Important Files Changed

Filename	Overview
litellm/proxy_auth/credentials.py	New credential provider module with solid OAuth2/JWT token management, proper caching, and clean protocol-based design
litellm/main.py	Auth injection added to completion() and embedding(), but missing from other API methods like text_completion(), transcription(), speech(), and image_generation() if they exist
tests/litellm/test_proxy_auth.py	Comprehensive unit tests covering all credential providers, token caching, refresh logic, and integration with litellm module

Sequence Diagram

sequenceDiagram
    participant User
    participant litellm
    participant ProxyAuthHandler
    participant Credential
    participant OAuth2Server
    participant LiteLLMProxy

    User->>litellm: setup proxy_auth with credential and scope
    User->>litellm: completion(model, messages, ...)
    litellm->>litellm: Check if proxy_auth is set
    alt proxy_auth is configured
        litellm->>ProxyAuthHandler: get_auth_headers()
        ProxyAuthHandler->>ProxyAuthHandler: Check cached token validity
        alt token missing or expires within 60s
            ProxyAuthHandler->>Credential: get_token(scope)
            alt AzureADCredential
                Credential->>OAuth2Server: Request Azure AD token
                OAuth2Server-->>Credential: Return token with expiration
            else GenericOAuth2Credential
                Credential->>OAuth2Server: POST client credentials grant
                OAuth2Server-->>Credential: Return token with expiration
            end
            Credential-->>ProxyAuthHandler: AccessToken object
            ProxyAuthHandler->>ProxyAuthHandler: Cache token
        end
        ProxyAuthHandler-->>litellm: Authorization headers dict
        litellm->>litellm: Update request headers
    end
    litellm->>LiteLLMProxy: HTTP Request with Authorization
    LiteLLMProxy-->>litellm: Response
    litellm-->>User: ModelResponse

Loading

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[ghost]

Hi @Chesars can you document this please?

[Chesars]

Hi @Chesars can you document this please?

Hi @krrishdholakia , added in #20680