docs: add SDK proxy authentication (OAuth2/JWT auto-refresh)

[Chesars]

Relevant issues

Docs for #19834 / PR #20238

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

📖 Documentation

Changes

Adds documentation for the litellm.proxy_auth feature (introduced in PR #20238) that automatically obtains and refreshes OAuth2/JWT tokens when connecting the LiteLLM Python SDK to a proxy server.

Files changed:

• docs/my-website/docs/proxy_auth.md (new) — Full documentation page covering:

  • Quick Start with Azure AD (DefaultAzureCredential + ClientSecretCredential)
  • Generic OAuth2 (Okta, Auth0, Keycloak) usage
  • Custom credential providers via TokenCredential protocol
  • How it works (architecture diagram)
  • Complete API reference (ProxyAuthHandler, AzureADCredential, GenericOAuth2Credential, AccessToken)
  • Provider-specific examples (Keycloak, Okta, Auth0, Azure Managed Identity)
  • Combining with use_litellm_proxy

• docs/my-website/sidebars.js — Added proxy_auth to the SDK > Configuration sidebar section

• docs/my-website/docs/providers/litellm_proxy.md — Added cross-reference section for OAuth2/JWT authentication linking to the new page

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 8, 2026 0:20am

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds comprehensive documentation for the litellm.proxy_auth feature that enables automatic OAuth2/JWT token management when connecting the LiteLLM Python SDK to an authenticated proxy server.

Key Changes

• New documentation page (proxy_auth.md) covering the complete API with examples for Azure AD (DefaultAzureCredential and ClientSecretCredential), generic OAuth2 providers (Okta, Auth0, Keycloak), and custom credential providers
• Updated proxy documentation with a new OAuth2/JWT Authentication section linking to the detailed guide
• Sidebar navigation updated to include proxy_auth in SDK Configuration section

Documentation Quality

The documentation is well-structured with:

• Clear quick-start examples for common scenarios
• Comprehensive API reference with parameter tables
• Provider-specific configuration examples
• Architecture diagram explaining the token lifecycle
• Integration guidance with use_litellm_proxy

All code examples were verified against the actual implementation in litellm/proxy_auth/ and litellm/main.py. The documented classes (ProxyAuthHandler, AzureADCredential, GenericOAuth2Credential, AccessToken) match the implementation, and the documented behavior (60-second refresh buffer, automatic header injection for completion() and embedding()) is accurate.

Confidence Score: 5/5

• This documentation-only PR is safe to merge with no risk
• This is a documentation-only PR that adds comprehensive, accurate documentation for an existing feature (proxy_auth). All code examples were verified against the actual implementation. No code changes, no performance impact, and the documentation follows the repository's established patterns and style.
• No files require special attention

Important Files Changed

Filename	Overview
docs/my-website/docs/proxy_auth.md	New comprehensive documentation for proxy_auth feature with examples for Azure AD, OAuth2 providers, and custom credentials - all examples verified against implementation
docs/my-website/docs/providers/litellm_proxy.md	Added OAuth2/JWT authentication section with cross-reference to detailed proxy_auth documentation
docs/my-website/sidebars.js	Added proxy_auth to SDK Configuration sidebar section in correct location

Sequence Diagram

sequenceDiagram
    participant User as User Code
    participant SDK as LiteLLM SDK
    participant Handler as ProxyAuthHandler
    participant IDP as Identity Provider
    participant Proxy as LiteLLM Proxy

    Note over User,Proxy: Setup Phase
    User->>Handler: Configure with credential and scope
    
    Note over User,Proxy: First API Call
    User->>SDK: completion() or embedding()
    SDK->>Handler: Request auth headers
    Handler->>Handler: Check cache (empty)
    Handler->>IDP: Request token with scope
    IDP-->>Handler: Return access token
    Handler->>Handler: Cache token
    Handler-->>SDK: Return authorization headers
    SDK->>Proxy: API request with headers
    Proxy-->>SDK: API response
    SDK-->>User: Return response
    
    Note over User,Proxy: Subsequent Calls (Token Valid)
    User->>SDK: completion() or embedding()
    SDK->>Handler: Request auth headers
    Handler->>Handler: Return cached token
    Handler-->>SDK: Return authorization headers
    SDK->>Proxy: API request with headers
    Proxy-->>SDK: API response
    SDK-->>User: Return response
    
    Note over User,Proxy: Token Refresh (Expiring Soon)
    User->>SDK: completion() or embedding()
    SDK->>Handler: Request auth headers
    Handler->>Handler: Detect expiration within 60s
    Handler->>IDP: Request new token
    IDP-->>Handler: Return new access token
    Handler->>Handler: Update cache
    Handler-->>SDK: Return authorization headers
    SDK->>Proxy: API request with headers
    Proxy-->>SDK: API response
    SDK-->>User: Return response

Loading

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}