User Management

API endpoints for managing users in the LiteLLM proxy

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

user_id · string · required

Unique identifier for the user.

user_email · string

User’s email address.

user_role · string

User role.

Options: "proxy_admin", "proxy_admin_viewer", "internal_user", "internal_user_viewer", "team", "customer"

teams · array

Teams this user belongs to.

{"teams": ["team-1", "team-2"]}

max_budget · number

Maximum spending limit for the user in USD.

models · array

Models this user can access.

tpm_limit · integer

User-specific tokens per minute limit.

rpm_limit · integer

User-specific requests per minute limit.

budget_duration · string

Budget reset period.

metadata · object

Custom metadata for the user.

Response

user_id · string

The created user ID.

user_email · string

User email.

user_role · string

User role.

teams · array

Teams the user belongs to.

max_budget · number

Budget limit.

Example

curl -X POST http://localhost:4000/user/new \
  -H "Authorization: Bearer sk-admin-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "[e-mail]",
    "user_email": "[e-mail]",
    "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": "[e-mail]",
        "user_email": "[e-mail]",
        "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

team_id · string

Filter by team ID.

role · string

Filter by user role.

Response

users · array

Array of user objects.

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

user_id · string · required

The user ID to query.

Response

user_id · string

User identifier.

user_email · string

User email.

user_role · string

User role.

teams · array

Teams the user belongs to.

spend · number

Current spend.

max_budget · number

Budget limit.

models · array

Accessible models.

keys · array

API keys associated with this user.

Example

curl -X GET 'http://localhost:4000/user/info?user_id=[e-mail]' \
  -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": "[e-mail]"}
)

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

user_id · string · required

The user ID to update.

user_email · string

Update user email.

user_role · string

Update user role.

teams · array

Update teams.

max_budget · number

Update budget limit.

models · array

Update accessible models.

tpm_limit · integer

Update TPM limit.

rpm_limit · integer

Update RPM limit.

Example

curl -X POST http://localhost:4000/user/update \
  -H "Authorization: Bearer sk-admin-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "[e-mail]",
    "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": "[e-mail]",
        "max_budget": 200.0,
        "models": ["gpt-4", "claude-2"]
    }
)

---

Delete User

POST /user/delete

Delete a user.

Request Body

user_ids · array · required

Array of user IDs to delete.

{"user_ids": ["[e-mail]", "[e-mail]"]}

Example

curl -X POST http://localhost:4000/user/delete \
  -H "Authorization: Bearer sk-admin-xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_ids": ["[e-mail]"]}'

import requests

response = requests.post(
    "http://localhost:4000/user/delete",
    headers={"Authorization": "Bearer sk-admin-xxx"},
    json={"user_ids": ["[e-mail]"]}
)

---

User Roles

LiteLLM supports different user roles with varying permissions:

Admin Roles

proxy_admin · role

Full admin access to the proxy.

• Can manage all keys, teams, and users
• Can view all spend and usage
• Can modify proxy settings

proxy_admin_viewer · role

View-only admin access.

• Can view all keys, teams, and users
• Can view all spend and usage
• Cannot make changes

Internal User Roles

internal_user · role

Standard internal user.

• Can create/view/delete their own keys
• Can view their own spend
• Limited to their assigned teams and models

internal_user_viewer · role

View-only internal user.

• Can view their own keys
• Can view their own spend
• Cannot create or delete keys

Other Roles

team · role

Team-level access (used for JWT auth).

customer · role

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": "[e-mail]",
        "user_email": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]"}
)

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": "[e-mail]",
        "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

1. Individual budgets: Each user has their own budget limit
2. Spend tracking: All requests made by user’s keys are tracked
3. Budget enforcement: Requests rejected when user budget exceeded
4. 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": "[e-mail]",
        "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

Related

• Key Management
• Team Management
• POST /v1/chat/completions