Implementation:BerriAI Litellm Enterprise API Key Auth

Attribute	Value
Sources	enterprise/litellm_enterprise/proxy/auth/user_api_key_auth.py
Domains	Authentication, Enterprise, Proxy Auth
Last Updated	2026-02-15 16:00 GMT

Overview

enterprise_custom_auth is an enterprise authentication function that wraps custom user-provided auth handlers with configurable execution modes (on, off, auto) to control when custom authentication logic runs relative to the standard LiteLLM auth pipeline.

Description

This module provides a single async function, enterprise_custom_auth, which acts as a dispatcher for user-provided custom authentication handlers. It supports three modes configured via custom_auth_settings:

• "on" -- Always runs the custom auth handler. If it raises, the request is rejected.
• "off" -- Skips the custom auth handler entirely, returning None to fall through to standard LiteLLM authentication.
• "auto" -- Attempts to run the custom auth handler. If it raises a ProxyException, the exception is re-raised (explicit rejection). If it raises any other exception, the error is logged and the function returns None, allowing LiteLLM's standard auth to handle the request.

If no custom_auth_settings are configured (i.e., None), the custom auth handler is called directly without mode checking.

If no user_custom_auth handler is provided, the function returns None immediately.

Usage

This function is called by the LiteLLM proxy's authentication pipeline when a custom auth handler is registered. Configure via custom_auth_settings in the enterprise proxy server module.

Code Reference

Source Location

enterprise/litellm_enterprise/proxy/auth/user_api_key_auth.py

Signature

async def enterprise_custom_auth(
    request: Request,
    api_key: str,
    user_custom_auth: Optional[Any],
) -> Optional[UserAPIKeyAuth]: ...

Import

from litellm_enterprise.proxy.auth.user_api_key_auth import enterprise_custom_auth

I/O Contract

Inputs

Parameter	Type	Description
request	fastapi.Request	The incoming FastAPI request.
api_key	str	The API key extracted from the request.
user_custom_auth	Optional[Any]	A callable async function implementing custom auth logic.

Configuration (from litellm_enterprise.proxy.proxy_server):

Setting	Type	Description
custom_auth_settings["mode"]	str	One of "on", "off", "auto".

Outputs

Output	Type	Description
Auth result	Optional[UserAPIKeyAuth]	The authentication result from the custom handler, or None to fall through to standard auth.

Usage Examples

# Enterprise proxy config with custom auth in "auto" mode
general_settings:
  custom_auth: "my_auth_module.my_custom_auth_handler"
  custom_auth_settings:
    mode: "auto"

# Custom auth handler implementation
from fastapi import Request
from litellm.proxy._types import UserAPIKeyAuth

async def my_custom_auth_handler(request: Request, api_key: str) -> UserAPIKeyAuth:
    # Validate against external auth service
    user_info = await validate_with_external_service(api_key)
    return UserAPIKeyAuth(
        api_key=api_key,
        user_id=user_info["user_id"],
        user_email=user_info["email"],
    )

Related Pages

• BerriAI_Litellm_Enterprise_SSO_Handler -- Enterprise custom SSO authentication