Documentation Index
Fetch the complete documentation index at: https://mintlify.com/BerriAI/litellm/llms.txt
Use this file to discover all available pages before exploring further.
Overview
User management endpoints allow you to create and manage users with individual budgets, access control, and usage tracking.
Create User
POST /user/new
Create a new user.
Request Body
Unique identifier for the user.
User role.Options: "proxy_admin", "proxy_admin_viewer", "internal_user", "internal_user_viewer", "team", "customer"
Teams this user belongs to.{"teams": ["team-1", "team-2"]}
Maximum spending limit for the user in USD.
Models this user can access.
User-specific tokens per minute limit.
User-specific requests per minute limit.
Custom metadata for the user.
Response
Teams the user belongs to.
Example
curl -X POST http://localhost:4000/user/new \
-H "Authorization: Bearer sk-admin-xxx" \
-H "Content-Type: application/json" \
-d '{
"user_id": "john@company.com",
"user_email": "john@company.com",
"user_role": "internal_user",
"teams": ["engineering-team"],
"max_budget": 100.0,
"models": ["gpt-4", "gpt-3.5-turbo"],
"metadata": {
"department": "Engineering"
}
}'
import requests
response = requests.post(
"http://localhost:4000/user/new",
headers={"Authorization": "Bearer sk-admin-xxx"},
json={
"user_id": "john@company.com",
"user_email": "john@company.com",
"user_role": "internal_user",
"teams": ["engineering-team"],
"max_budget": 100.0
}
)
user = response.json()
print(f"Created user: {user['user_id']}")
List Users
GET /user/list
List all users.
Query Parameters
Response
Example
curl -X GET 'http://localhost:4000/user/list' \
-H "Authorization: Bearer sk-admin-xxx"
import requests
response = requests.get(
"http://localhost:4000/user/list",
headers={"Authorization": "Bearer sk-admin-xxx"}
)
users = response.json()["users"]
for user in users:
print(f"User: {user['user_email']}")
print(f" Role: {user['user_role']}")
print(f" Spend: ${user.get('spend', 0):.2f}")
Get User Info
GET /user/info
Get detailed information about a specific user.
Query Parameters
Response
Teams the user belongs to.
API keys associated with this user.
Example
curl -X GET 'http://localhost:4000/user/info?user_id=john@company.com' \
-H "Authorization: Bearer sk-admin-xxx"
import requests
response = requests.get(
"http://localhost:4000/user/info",
headers={"Authorization": "Bearer sk-admin-xxx"},
params={"user_id": "john@company.com"}
)
user = response.json()
print(f"User: {user['user_email']}")
print(f"Budget: ${user.get('spend', 0):.2f} / ${user['max_budget']:.2f}")
print(f"Keys: {len(user['keys'])}")
Update User
POST /user/update
Update an existing user.
Request Body
Update accessible models.
Example
curl -X POST http://localhost:4000/user/update \
-H "Authorization: Bearer sk-admin-xxx" \
-H "Content-Type: application/json" \
-d '{
"user_id": "john@company.com",
"max_budget": 200.0,
"user_role": "proxy_admin"
}'
import requests
response = requests.post(
"http://localhost:4000/user/update",
headers={"Authorization": "Bearer sk-admin-xxx"},
json={
"user_id": "john@company.com",
"max_budget": 200.0,
"models": ["gpt-4", "claude-2"]
}
)
Delete User
POST /user/delete
Delete a user.
Request Body
Array of user IDs to delete.{"user_ids": ["user1@company.com", "user2@company.com"]}
Example
curl -X POST http://localhost:4000/user/delete \
-H "Authorization: Bearer sk-admin-xxx" \
-H "Content-Type: application/json" \
-d '{"user_ids": ["john@company.com"]}'
import requests
response = requests.post(
"http://localhost:4000/user/delete",
headers={"Authorization": "Bearer sk-admin-xxx"},
json={"user_ids": ["john@company.com"]}
)
User Roles
LiteLLM supports different user roles with varying permissions:
Admin Roles
Full admin access to the proxy.
- Can manage all keys, teams, and users
- Can view all spend and usage
- Can modify proxy settings
View-only admin access.
- Can view all keys, teams, and users
- Can view all spend and usage
- Cannot make changes
Internal User Roles
Standard internal user.
- Can create/view/delete their own keys
- Can view their own spend
- Limited to their assigned teams and models
View-only internal user.
- Can view their own keys
- Can view their own spend
- Cannot create or delete keys
Other Roles
Team-level access (used for JWT auth).
External customer access.
Complete Example
import requests
import json
BASE_URL = "http://localhost:4000"
ADMIN_KEY = "sk-admin-xxx"
headers = {
"Authorization": f"Bearer {ADMIN_KEY}",
"Content-Type": "application/json"
}
# 1. Create a user
user_response = requests.post(
f"{BASE_URL}/user/new",
headers=headers,
json={
"user_id": "alice@company.com",
"user_email": "alice@company.com",
"user_role": "internal_user",
"max_budget": 100.0,
"models": ["gpt-4"],
"metadata": {"department": "Product"}
}
)
print(f"Created user: {user_response.json()['user_id']}")
# 2. Create a key for the user
key_response = requests.post(
f"{BASE_URL}/key/generate",
headers=headers,
json={
"user_id": "alice@company.com",
"models": ["gpt-4"],
"duration": "30d"
}
)
user_key = key_response.json()["key"]
print(f"Created key: {user_key}")
# 3. User makes a request with their key
import openai
client = openai.OpenAI(
api_key=user_key,
base_url=BASE_URL
)
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}]
)
print(f"User request successful")
# 4. Check user's spending
info_response = requests.get(
f"{BASE_URL}/user/info",
headers=headers,
params={"user_id": "alice@company.com"}
)
user = info_response.json()
print(f"\nUser spend: ${user['spend']:.4f} / ${user['max_budget']:.2f}")
# 5. Update user's budget
update_response = requests.post(
f"{BASE_URL}/user/update",
headers=headers,
json={
"user_id": "alice@company.com",
"max_budget": 200.0
}
)
print("Updated user budget to $200")
# 6. List all users
list_response = requests.get(
f"{BASE_URL}/user/list",
headers=headers
)
users = list_response.json()["users"]
print(f"\nTotal users: {len(users)}")
for user in users:
print(f" - {user['user_email']}: ${user.get('spend', 0):.4f}")
User Budget Tracking
How User Budgets Work
- Individual budgets: Each user has their own budget limit
- Spend tracking: All requests made by user’s keys are tracked
- Budget enforcement: Requests rejected when user budget exceeded
- Budget reset: Can reset daily, monthly, or never
User + Team Budgets
Users can belong to teams and have individual budgets:
# Create user with team membership
response = requests.post(
"http://localhost:4000/user/new",
headers={"Authorization": "Bearer sk-admin-xxx"},
json={
"user_id": "bob@company.com",
"teams": ["engineering-team"], # Team budget: $1000
"max_budget": 50.0 # User budget: $50
}
)
# Bob's requests count against:
# 1. His individual $50 budget
# 2. The engineering team's $1000 budget
# Whichever is exceeded first will block requests