Skip to main content

Custom Auth

Authenticate API requests with a Python handler that validates your application's credentials and returns the caller's LiteLLM identity.

How it works​

LiteLLM passes the FastAPI Request and bearer credential to your async handler. Return UserAPIKeyAuth after validating the credential, or raise an exception to reject it. The returned identity supplies usage attribution and any configured authorization checks.

Enforcement with custom auth

Returning UserAPIKeyAuth does not enable every authorization check. Rate limits set on the object apply directly; budgets and model access require additional flags. Configure them using Custom auth permissions.

Prerequisites​

Start with a working proxy and a configured model; the examples use my-model. Make your Python module available beside config.yaml or on the proxy's Python import path. Store the credential used by the example in the proxy's CUSTOM_AUTH_TOKEN environment variable.

For an existing authentication service, replace the example's credential comparison with that service's validation and return its verified identity.

Setup​

1. Write the handler​

Save this as custom_auth.py. The example validates one application's credential and identifies it as integration-client.

custom_auth.py
import os
from secrets import compare_digest

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


async def user_api_key_auth(request: Request, api_key: str) -> UserAPIKeyAuth:
expected_token = os.environ["CUSTOM_AUTH_TOKEN"]
if not expected_token or not api_key or not compare_digest(api_key, expected_token):
raise ProxyException(
message="Invalid credential",
type="authentication_error",
param="api_key",
code=401,
)
return UserAPIKeyAuth(api_key=api_key, user_id="integration-client")

2. Configure the proxy​

Add the module and function name to your existing configuration. Keep your model and database settings.

config.yaml
general_settings:
custom_auth: custom_auth.user_api_key_auth

3. Start the proxy​

litellm --config config.yaml

Test authentication​

Set CUSTOM_AUTH_TOKEN in your client environment to the same credential, then send it as the bearer token:

curl 'http://localhost:4000/v1/chat/completions' \
-H "Authorization: Bearer $CUSTOM_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"model":"my-model","messages":[{"role":"user","content":"Hello"}]}'

A valid credential passes authentication. Repeat with an incorrect credential; the example returns 401. If the valid caller is denied a model or exceeds a limit, check authorization separately.

Configuration reference​

Caller identity​

Return the identity fields LiteLLM uses for usage attribution. The *_id fields also identify the database records loaded when custom_auth_run_common_checks: true.

FieldMeaning
api_keyCaller credential; LiteLLM hashes it for internal use.
tokenHashed token for internal use.
key_aliasA display name for the credential.
user_id, user_emailVerified caller identity.
user_roleLiteLLM role; see roles and permissions.
team_id, org_id, end_user_idTeam, organization, and end-user identities for the request.

For model permissions, budgets, and rate-limit fields, use Custom auth permissions.

Token expiration​

Return the credential's original expiration time as expires, and enable the expiry check:

litellm_settings:
enable_post_custom_auth_checks: true

This helper accepts the expiration time obtained from your credential validator:

from datetime import datetime
from litellm.proxy._types import UserAPIKeyAuth


def authentication_result(api_key: str, expires_at: datetime) -> UserAPIKeyAuth:
return UserAPIKeyAuth(api_key=api_key, expires=expires_at)

Use a timezone-aware expiration time. Recomputing it from the current time on each request would keep extending the credential's lifetime.

Accept Virtual Keys alongside custom credentials​

Since v1.72.2
Enterprise feature

Using Custom Auth with LiteLLM Virtual Keys requires a LiteLLM Enterprise license. Start a free 30-day trial or book a demo. See what Enterprise includes.

Set mode: auto to try the custom handler first and fall back to normal Virtual Key authentication when it raises an ordinary exception. A ProxyException is an explicit rejection and does not trigger fallback.

A handler can also return an existing Virtual Key string after validating an external credential. LiteLLM then authenticates that key through its normal path:

custom_auth_auto.py
import os
from secrets import compare_digest

from fastapi import Request


async def user_api_key_auth(request: Request, api_key: str) -> str:
expected_token = os.environ["CUSTOM_AUTH_TOKEN"]
if not expected_token:
raise ValueError("Custom credential is not configured")
if api_key and compare_digest(api_key, expected_token):
return os.environ["LITELLM_VIRTUAL_KEY"]
raise ValueError("Credential not handled by custom auth")

Set LITELLM_VIRTUAL_KEY on the proxy to an existing key, then configure the handler:

general_settings:
custom_auth: custom_auth_auto.user_api_key_auth
custom_auth_settings:
mode: auto

Test with the external credential and with an existing Virtual Key. Both should authenticate. A credential accepted by neither path is rejected.

ModeBehavior
onRun the custom handler. This is also the behavior when custom auth is configured without custom_auth_settings.
offSkip the custom handler and use normal authentication.
autoTry the custom handler; ordinary exceptions fall back to normal authentication. ProxyException is propagated.

Return a specific error​

Raise ProxyException with the response message and HTTP code, as in the setup example. Let it propagate from the handler. Catching it and raising a generic exception discards the intended response and can enable fallback in auto mode.

Troubleshooting​

SymptomCheck
Handler cannot be importedConfirm the filename, function name, import path, and mounted file match general_settings.custom_auth.
Every credential is rejectedConfirm the validator's configuration and secret are present in the proxy process.
A Virtual Key is rejected before fallbackIn auto mode, raise an ordinary exception for credentials the custom handler does not handle. Reserve ProxyException for explicit denials.
Custom error details disappearRemove blanket exception handlers that replace ProxyException.
An expired credential still worksReturn its original expires value and enable enable_post_custom_auth_checks.
Budget or model restrictions do not applyCheck custom auth enforcement flags.

Use Custom auth permissions for authorization, Virtual Keys for credential management, or custom SSO hooks for browser sign-in callbacks.