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

# Virtual Keys (API Key Management)

> Generate and manage virtual API keys with budgets and permissions

## Overview

Virtual keys allow you to create API keys with:

* Custom budgets and rate limits
* Model access restrictions
* Expiration dates
* Team associations
* Metadata and tags

## Generate a Key

Create a virtual key using the master key:

```bash theme={null}
curl -X POST 'http://localhost:4000/key/generate' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "models": ["gpt-3.5-turbo", "gpt-4"],
    "max_budget": 10.0,
    "duration": "30d"
  }'
```

Response:

```json theme={null}
{
  "key": "sk-1234567890abcdef",
  "key_name": null,
  "expires": "2024-04-15T10:30:00Z",
  "models": ["gpt-3.5-turbo", "gpt-4"],
  "max_budget": 10.0,
  "budget_duration": "30d",
  "budget_reset_at": "2024-04-15T10:30:00Z"
}
```

## Key Generation Parameters

### Basic Parameters

```json theme={null}
{
  "key_name": "production-api-key",      // Optional friendly name
  "duration": "30d",                     // Key expiration (e.g., 30d, 24h, null for no expiry)
  "models": ["gpt-3.5-turbo", "gpt-4"], // Allowed models
  "metadata": {                          // Custom metadata
    "environment": "production",
    "team": "backend"
  }
}
```

### Budget Parameters

```json theme={null}
{
  "max_budget": 100.0,           // Maximum spend in USD
  "budget_duration": "30d",      // Budget reset period
  "soft_budget": 80.0            // Alert threshold (80% of max_budget)
}
```

### Rate Limiting

```json theme={null}
{
  "rpm": 100,        // Requests per minute
  "tpm": 100000,     // Tokens per minute
  "max_parallel_requests": 10
}
```

### Team Association

```json theme={null}
{
  "team_id": "team-abc-123",
  "user_id": "user-xyz-456"
}
```

### Complete Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'http://localhost:4000/key/generate' \
    -H 'Authorization: Bearer sk-1234' \
    -H 'Content-Type: application/json' \
    -d '{
      "key_name": "production-backend",
      "duration": "90d",
      "models": ["gpt-3.5-turbo", "gpt-4"],
      "max_budget": 100.0,
      "budget_duration": "30d",
      "soft_budget": 80.0,
      "rpm": 100,
      "tpm": 100000,
      "metadata": {
        "environment": "production",
        "team": "backend"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'http://localhost:4000/key/generate',
      headers={
          'Authorization': 'Bearer sk-1234',
          'Content-Type': 'application/json'
      },
      json={
          'key_name': 'production-backend',
          'duration': '90d',
          'models': ['gpt-3.5-turbo', 'gpt-4'],
          'max_budget': 100.0,
          'budget_duration': '30d',
          'soft_budget': 80.0,
          'rpm': 100,
          'tpm': 100000,
          'metadata': {
              'environment': 'production',
              'team': 'backend'
          }
      }
  )

  key_data = response.json()
  print(f"Generated key: {key_data['key']}")
  ```
</CodeGroup>

## Get Key Information

Retrieve information about a key:

```bash theme={null}
curl -X GET 'http://localhost:4000/key/info' \
  -H 'Authorization: Bearer sk-1234567890abcdef'
```

Response:

```json theme={null}
{
  "key": "sk-1234...def",
  "key_name": "production-backend",
  "team_id": null,
  "max_budget": 100.0,
  "spend": 45.23,
  "budget_reset_at": "2024-04-15T10:30:00Z",
  "models": ["gpt-3.5-turbo", "gpt-4"],
  "rpm": 100,
  "tpm": 100000,
  "expires": "2024-07-15T10:30:00Z",
  "metadata": {
    "environment": "production",
    "team": "backend"
  }
}
```

## Update a Key

Modify key properties:

```bash theme={null}
curl -X POST 'http://localhost:4000/key/update' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "sk-1234567890abcdef",
    "max_budget": 200.0,
    "models": ["gpt-3.5-turbo", "gpt-4", "claude-3-opus"],
    "rpm": 200
  }'
```

<Warning>
  You can only update a key using the master key, not the key itself.
</Warning>

## Delete a Key

Revoke a virtual key:

```bash theme={null}
curl -X POST 'http://localhost:4000/key/delete' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "keys": ["sk-1234567890abcdef"]
  }'
```

## List All Keys

Get all virtual keys:

```bash theme={null}
curl -X GET 'http://localhost:4000/key/list' \
  -H 'Authorization: Bearer sk-1234'
```

## Key Auto-Rotation

Configure automatic key rotation:

```bash theme={null}
curl -X POST 'http://localhost:4000/key/generate' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "key_alias": "production-key",
    "auto_rotate": true,
    "rotation_interval": "90d",
    "models": ["gpt-3.5-turbo"],
    "max_budget": 100.0
  }'
```

The key will automatically rotate every 90 days. The `key_alias` remains constant while the underlying key changes.

## Budget Tracking

### Check Spend

Monitor key spending:

```bash theme={null}
curl -X GET 'http://localhost:4000/key/info' \
  -H 'Authorization: Bearer sk-1234567890abcdef'
```

The response includes:

* `spend`: Current spend
* `max_budget`: Budget limit
* `budget_reset_at`: When budget resets

### Budget Alerts

Set soft budget for alerts:

```json theme={null}
{
  "max_budget": 100.0,
  "soft_budget": 80.0  // Alert at 80% usage
}
```

Configure webhook for alerts in your config:

```yaml config.yaml theme={null}
litellm_settings:
  alerting:
    - slack
  alerting_threshold: 0.8  # Alert at 80% budget
  slack_webhook_url: os.environ/SLACK_WEBHOOK_URL
```

## Model Access Control

### Restrict to Specific Models

```json theme={null}
{
  "models": ["gpt-3.5-turbo", "gpt-4"]
}
```

Requests to other models will be rejected:

```json theme={null}
{
  "error": {
    "message": "API key does not have access to model: claude-3-opus",
    "type": "invalid_request_error"
  }
}
```

### Allow All Models

Omit the `models` parameter or use `null`:

```json theme={null}
{
  "models": null  // Access to all configured models
}
```

## Rate Limiting

### Per-Key Rate Limits

```json theme={null}
{
  "rpm": 100,        // 100 requests per minute
  "tpm": 100000,     // 100k tokens per minute
  "max_parallel_requests": 10  // Max concurrent requests
}
```

When rate limit is exceeded:

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "type": "rate_limit_error"
  }
}
```

## Team Keys

Generate keys associated with teams:

<Steps>
  <Step title="Create a Team">
    ```bash theme={null}
    curl -X POST 'http://localhost:4000/team/new' \
      -H 'Authorization: Bearer sk-1234' \
      -H 'Content-Type: application/json' \
      -d '{
        "team_alias": "engineering",
        "max_budget": 1000.0,
        "budget_duration": "30d"
      }'
    ```
  </Step>

  <Step title="Generate Team Key">
    ```bash theme={null}
    curl -X POST 'http://localhost:4000/key/generate' \
      -H 'Authorization: Bearer sk-1234' \
      -H 'Content-Type: application/json' \
      -d '{
        "team_id": "team-abc-123",
        "models": ["gpt-3.5-turbo"],
        "max_budget": 100.0
      }'
    ```
  </Step>
</Steps>

Team keys inherit team budgets and settings. The key budget is separate from the team budget.

## Key Metadata

Attach custom metadata to keys:

```json theme={null}
{
  "metadata": {
    "environment": "production",
    "service": "backend-api",
    "owner": "john@example.com",
    "cost_center": "engineering"
  }
}
```

Use metadata for:

* Cost allocation
* Usage tracking
* Access auditing
* Organizational reporting

## Security Best Practices

### 1. Master Key Protection

<Warning>
  Never expose the master key in client applications. Use virtual keys instead.
</Warning>

```bash theme={null}
# Store master key securely
export LITELLM_MASTER_KEY=$(cat /secure/path/master_key.txt)
```

### 2. Key Rotation

Rotate keys regularly:

```bash theme={null}
# Generate new key
curl -X POST 'http://localhost:4000/key/generate' ...

# Update applications
# Delete old key
curl -X POST 'http://localhost:4000/key/delete' \
  -H 'Authorization: Bearer sk-1234' \
  -d '{"keys": ["old-key"]}'
```

### 3. Principle of Least Privilege

Grant minimum required access:

```json theme={null}
{
  "models": ["gpt-3.5-turbo"],  // Only specific model
  "max_budget": 10.0,            // Low budget
  "duration": "7d",              // Short expiration
  "rpm": 10                      // Low rate limit
}
```

### 4. Monitor Usage

Regularly audit key usage:

```bash theme={null}
# List all keys
curl -X GET 'http://localhost:4000/key/list' \
  -H 'Authorization: Bearer sk-1234'

# Check spend
curl -X GET 'http://localhost:4000/spend/keys' \
  -H 'Authorization: Bearer sk-1234'
```

## Programmatic Key Management

<CodeGroup>
  ```python Python SDK theme={null}
  import requests

  class LiteLLMKeyManager:
      def __init__(self, base_url, master_key):
          self.base_url = base_url
          self.headers = {
              'Authorization': f'Bearer {master_key}',
              'Content-Type': 'application/json'
          }
      
      def create_key(self, **kwargs):
          response = requests.post(
              f'{self.base_url}/key/generate',
              headers=self.headers,
              json=kwargs
          )
          return response.json()
      
      def delete_key(self, key):
          response = requests.post(
              f'{self.base_url}/key/delete',
              headers=self.headers,
              json={'keys': [key]}
          )
          return response.json()
      
      def get_key_info(self, key):
          response = requests.get(
              f'{self.base_url}/key/info',
              headers={'Authorization': f'Bearer {key}'}
          )
          return response.json()

  # Usage
  manager = LiteLLMKeyManager(
      base_url='http://localhost:4000',
      master_key='sk-1234'
  )

  # Create key
  key = manager.create_key(
      models=['gpt-3.5-turbo'],
      max_budget=10.0,
      duration='30d'
  )
  print(f"Created: {key['key']}")

  # Get info
  info = manager.get_key_info(key['key'])
  print(f"Spend: ${info['spend']}")

  # Delete key
  manager.delete_key(key['key'])
  ```

  ```javascript JavaScript SDK theme={null}
  class LiteLLMKeyManager {
    constructor(baseUrl, masterKey) {
      this.baseUrl = baseUrl;
      this.headers = {
        'Authorization': `Bearer ${masterKey}`,
        'Content-Type': 'application/json'
      };
    }

    async createKey(params) {
      const response = await fetch(`${this.baseUrl}/key/generate`, {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify(params)
      });
      return response.json();
    }

    async deleteKey(key) {
      const response = await fetch(`${this.baseUrl}/key/delete`, {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({ keys: [key] })
      });
      return response.json();
    }

    async getKeyInfo(key) {
      const response = await fetch(`${this.baseUrl}/key/info`, {
        headers: { 'Authorization': `Bearer ${key}` }
      });
      return response.json();
    }
  }

  // Usage
  const manager = new LiteLLMKeyManager(
    'http://localhost:4000',
    'sk-1234'
  );

  // Create key
  const key = await manager.createKey({
    models: ['gpt-3.5-turbo'],
    max_budget: 10.0,
    duration: '30d'
  });
  console.log(`Created: ${key.key}`);

  // Get info
  const info = await manager.getKeyInfo(key.key);
  console.log(`Spend: $${info.spend}`);

  // Delete key
  await manager.deleteKey(key.key);
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Budget Alerts" icon="bell" href="/proxy/budget-alerts">
    Set up spending alerts and notifications
  </Card>

  <Card title="Configuration" icon="gear" href="/proxy/configs">
    Advanced proxy configuration
  </Card>

  <Card title="Quick Start" icon="rocket" href="/proxy/quick-start">
    Get started with the proxy
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/proxy/docker-deployment">
    Deploy in production
  </Card>
</CardGroup>