Implementation:BerriAI Litellm Custom Auth Template

Attribute	Value
Sources	`litellm/proxy/custom_auth_auto.py`
Domains	Proxy, Authentication, Extensibility, Templates
Last Updated	2026-02-15 16:00 GMT

Overview

custom_auth_auto is an example template demonstrating how to implement a custom API key authentication function for the LiteLLM proxy server.

Description

This module provides a reference implementation of a custom authentication handler for the LiteLLM proxy. The user_api_key_auth async function receives a FastAPI Request object and the extracted api_key string, and must return either a UserAPIKeyAuth object or a string representing the authorized API key. The example demonstrates three patterns: (1) accepting keys with a specific prefix ("my-custom-key") and returning a mapped internal key, (2) raising a structured ProxyException with specific error types and HTTP codes for known invalid keys, and (3) raising a generic Exception for all other cases. This template is referenced in the proxy's YAML configuration via the custom_auth field.

Usage

Copy and modify this template when you need custom API key validation logic for the LiteLLM proxy. Configure it in your proxy_server_config.yaml by setting custom_auth: litellm.proxy.custom_auth_auto.user_api_key_auth (or your own module path).

Code Reference

Source Location

litellm/proxy/custom_auth_auto.py

Signature

async def user_api_key_auth(request: Request, api_key: str) -> Union[UserAPIKeyAuth, str]

Import

from litellm.proxy.custom_auth_auto import user_api_key_auth

I/O Contract

Inputs

Parameter	Type	Description
`request`	`fastapi.Request`	The incoming FastAPI request object.
`api_key`	`str`	The API key extracted from the request (typically from Authorization header).

Outputs

Return Type	Description
`Union[UserAPIKeyAuth, str]`	A `UserAPIKeyAuth` object containing user/key metadata, or a string representing the authorized internal API key.

Exceptions

Exception	Description
`ProxyException`	Raised for structured error responses with specific HTTP status codes and error types.
`Exception`	Raised for generic authentication failures.

Usage Examples

# In proxy_server_config.yaml:
# general_settings:
#   custom_auth: my_module.user_api_key_auth

from fastapi import Request
from litellm.proxy._types import ProxyException, UserAPIKeyAuth

async def user_api_key_auth(request: Request, api_key: str):
    # Custom validation logic
    if api_key.startswith("my-custom-key"):
        return "sk-P1zJMdsqCPNN54alZd_ETw"  # Return mapped internal key
    if api_key == "invalid-api-key":
        raise ProxyException(
            message="Invalid API key",
            type="invalid_request_error",
            param="api_key",
            code=401,
        )
    raise Exception("Invalid API key")

Related Pages

BerriAI_Litellm_Custom_SSO_Template - Custom SSO handler template for the proxy
BerriAI_Litellm_Custom_Secret_Manager_Base - Custom secret manager for managing API keys
BerriAI_Litellm_Proxy_Auth_Credentials - OAuth2/JWT credential management for proxy authentication

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment