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": "[email protected]",
"user_email": "[email protected]",
"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": "[email protected]",
"user_email": "[email protected]",
"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/[email protected]' \
-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": "[email protected]"}
)
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": "[email protected]",
"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": "[email protected]",
"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. Example
curl -X POST http://localhost:4000/user/delete \
-H "Authorization: Bearer sk-admin-xxx" \
-H "Content-Type: application/json" \
-d '{"user_ids": ["[email protected]"]}'
import requests
response = requests.post(
"http://localhost:4000/user/delete",
headers={"Authorization": "Bearer sk-admin-xxx"},
json={"user_ids": ["[email protected]"]}
)
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": "[email protected]",
"user_email": "[email protected]",
"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": "[email protected]",
"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": "[email protected]"}
)
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": "[email protected]",
"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": "[email protected]",
"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