> ## 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.

# 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

<ParamField body="user_id" type="string" required>
  Unique identifier for the user.
</ParamField>

<ParamField body="user_email" type="string">
  User's email address.
</ParamField>

<ParamField body="user_role" type="string">
  User role.

  Options: `"proxy_admin"`, `"proxy_admin_viewer"`, `"internal_user"`, `"internal_user_viewer"`, `"team"`, `"customer"`
</ParamField>

<ParamField body="teams" type="array">
  Teams this user belongs to.

  ```json theme={null}
  {"teams": ["team-1", "team-2"]}
  ```
</ParamField>

<ParamField body="max_budget" type="number">
  Maximum spending limit for the user in USD.
</ParamField>

<ParamField body="models" type="array">
  Models this user can access.
</ParamField>

<ParamField body="tpm_limit" type="integer">
  User-specific tokens per minute limit.
</ParamField>

<ParamField body="rpm_limit" type="integer">
  User-specific requests per minute limit.
</ParamField>

<ParamField body="budget_duration" type="string">
  Budget reset period.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata for the user.
</ParamField>

#### Response

<ResponseField name="user_id" type="string">
  The created user ID.
</ResponseField>

<ResponseField name="user_email" type="string">
  User email.
</ResponseField>

<ResponseField name="user_role" type="string">
  User role.
</ResponseField>

<ResponseField name="teams" type="array">
  Teams the user belongs to.
</ResponseField>

<ResponseField name="max_budget" type="number">
  Budget limit.
</ResponseField>

#### Example

```bash theme={null}
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"
    }
  }'
```

```python theme={null}
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

<ParamField query="team_id" type="string">
  Filter by team ID.
</ParamField>

<ParamField query="role" type="string">
  Filter by user role.
</ParamField>

#### Response

<ResponseField name="users" type="array">
  Array of user objects.
</ResponseField>

#### Example

```bash theme={null}
curl -X GET 'http://localhost:4000/user/list' \
  -H "Authorization: Bearer sk-admin-xxx"
```

```python theme={null}
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

<ParamField query="user_id" type="string" required>
  The user ID to query.
</ParamField>

#### Response

<ResponseField name="user_id" type="string">
  User identifier.
</ResponseField>

<ResponseField name="user_email" type="string">
  User email.
</ResponseField>

<ResponseField name="user_role" type="string">
  User role.
</ResponseField>

<ResponseField name="teams" type="array">
  Teams the user belongs to.
</ResponseField>

<ResponseField name="spend" type="number">
  Current spend.
</ResponseField>

<ResponseField name="max_budget" type="number">
  Budget limit.
</ResponseField>

<ResponseField name="models" type="array">
  Accessible models.
</ResponseField>

<ResponseField name="keys" type="array">
  API keys associated with this user.
</ResponseField>

#### Example

```bash theme={null}
curl -X GET 'http://localhost:4000/user/info?user_id=john@company.com' \
  -H "Authorization: Bearer sk-admin-xxx"
```

```python theme={null}
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

<ParamField body="user_id" type="string" required>
  The user ID to update.
</ParamField>

<ParamField body="user_email" type="string">
  Update user email.
</ParamField>

<ParamField body="user_role" type="string">
  Update user role.
</ParamField>

<ParamField body="teams" type="array">
  Update teams.
</ParamField>

<ParamField body="max_budget" type="number">
  Update budget limit.
</ParamField>

<ParamField body="models" type="array">
  Update accessible models.
</ParamField>

<ParamField body="tpm_limit" type="integer">
  Update TPM limit.
</ParamField>

<ParamField body="rpm_limit" type="integer">
  Update RPM limit.
</ParamField>

#### Example

```bash theme={null}
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"
  }'
```

```python theme={null}
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

<ParamField body="user_ids" type="array" required>
  Array of user IDs to delete.

  ```json theme={null}
  {"user_ids": ["user1@company.com", "user2@company.com"]}
  ```
</ParamField>

#### Example

```bash theme={null}
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"]}'
```

```python theme={null}
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

<ParamField path="proxy_admin" type="role">
  Full admin access to the proxy.

  * Can manage all keys, teams, and users
  * Can view all spend and usage
  * Can modify proxy settings
</ParamField>

<ParamField path="proxy_admin_viewer" type="role">
  View-only admin access.

  * Can view all keys, teams, and users
  * Can view all spend and usage
  * Cannot make changes
</ParamField>

### Internal User Roles

<ParamField path="internal_user" type="role">
  Standard internal user.

  * Can create/view/delete their own keys
  * Can view their own spend
  * Limited to their assigned teams and models
</ParamField>

<ParamField path="internal_user_viewer" type="role">
  View-only internal user.

  * Can view their own keys
  * Can view their own spend
  * Cannot create or delete keys
</ParamField>

### Other Roles

<ParamField path="team" type="role">
  Team-level access (used for JWT auth).
</ParamField>

<ParamField path="customer" type="role">
  External customer access.
</ParamField>

## Complete Example

```python theme={null}
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

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:

```python theme={null}
# 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
```

## Related

* [Key Management](/api/proxy/keys)
* [Team Management](/api/proxy/teams)
* [POST /v1/chat/completions](/api/proxy/chat-completions)