Implementation:BerriAI Litellm Generate Key Fn

Knowledge Sources	Domains	Last Updated
BerriAI/litellm repository	Authentication, API Key Generation, Access Control	2026-02-15

Overview

Concrete tool for generating API keys with scoped permissions and budget limits provided by the LiteLLM generate_key_fn endpoint handler.

Description

The generate_key_fn function is the async request handler for the /key/generate endpoint in the LiteLLM proxy server. It implements the full key creation workflow: authenticating the caller via user_api_key_auth, validating the request parameters, checking team membership and role-based creation policies, generating a unique key (or accepting a user-provided key), persisting the key record to the database with all associated metadata, and returning the key details to the caller.

Key features of the implementation:

• Caller authorization -- Validates that the caller has permission to create keys, enforcing that non-admin users can only create keys for themselves.
• Team-scoped key creation -- When a team_id is provided, verifies team membership, checks team key generation policies, and applies team-level model and budget restrictions.
• Custom auth hooks -- Supports a pluggable user_custom_key_generate coroutine for custom authorization logic.
• Budget validation -- Rejects negative max_budget and soft_budget values.
• Key rotation support -- Supports auto_rotate and rotation_interval parameters for automatic key regeneration.
• Event hooks -- Triggers post-creation hooks via KeyManagementEventHooks for actions like sending invite emails.

Usage

Use generate_key_fn by sending a POST request to the /key/generate endpoint of the LiteLLM proxy. This function is registered as a FastAPI route handler and is not typically called directly in application code.

Code Reference

Attribute	Value
Source Location	litellm/proxy/management_endpoints/key_management_endpoints.py, line 992
Signature	async def generate_key_fn(data: GenerateKeyRequest, user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), litellm_changed_by: Optional[str] = Header(None, ...)) -> GenerateKeyResponse
Route	POST /key/generate
Import	from litellm.proxy.management_endpoints.key_management_endpoints import generate_key_fn

I/O Contract

Inputs

Parameter	Type	Description
data	GenerateKeyRequest	Pydantic model containing key configuration: duration, key_alias, key, team_id, user_id, organization_id, models, max_budget, budget_duration, rpm_limit, tpm_limit, metadata, permissions, guardrails, tags, expires, auto_rotate, rotation_interval, and more.
user_api_key_dict	UserAPIKeyAuth	Authentication context of the caller, injected via FastAPI dependency. Contains caller's user_id, user_role, team_id, and permissions.
litellm_changed_by	Optional[str]	HTTP header for audit trail -- tracks which authorized user performed the action on behalf of another user.

Outputs

Field	Type	Description
key	str	The generated API key string (e.g., sk-...). Only returned once; stored as a hash in the database.
expires	Optional[datetime]	Expiration timestamp for the key, or None if no expiration is set.
user_id	str	The user ID associated with the generated key.
token_id	str	The unique identifier for the key record in the database.

Usage Examples

Generating a basic API key via curl:

curl --location 'http://0.0.0.0:4000/key/generate' \
    --header 'Authorization: Bearer sk-master-key-1234' \
    --header 'Content-Type: application/json' \
    --data '{
        "key_alias": "my-app-key",
        "max_budget": 100.0,
        "budget_duration": "30d",
        "models": ["gpt-4", "claude-3"],
        "metadata": {"app": "my-application"}
    }'

Generating a team-scoped key with rate limits:

<synttml lang="bash"> curl --location 'http://0.0.0.0:4000/key/generate' \

   --header 'Authorization: Bearer sk-master-key-1234' \
   --header 'Content-Type: application/json' \
   --data '{
       "team_id": "team-engineering",
       "user_id": "user-123",
       "rpm_limit": 100,
       "tpm_limit": 50000,
       "max_budget": 50.0,
       "duration": "30d"
   }'

</syntaxhighlight>

Generating a key with auto-rotation:

curl --location 'http://0.0.0.0:4000/key/generate' \
    --header 'Authorization: Bearer sk-master-key-1234' \
    --header 'Content-Type: application/json' \
    --data '{
        "key_alias": "rotating-key",
        "auto_rotate": true,
        "rotation_interval": "90d",
        "max_budget": 200.0
    }'

Using the generated key with the Python OpenAI client:

from openai import OpenAI

# Use the key returned from /key/generate
client = OpenAI(
    api_key="sk-generated-key-value",
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Related Pages

• Principle:BerriAI_Litellm_API_Key_Management
• Environment:BerriAI_Litellm_PostgreSQL_Database