---
title: "Generate Key Fn"
method: POST
path: "/key/generate"
tags: ["key management"]
---

# Generate Key Fn

`POST /key/generate`

Generate an API key based on the provided data.

Docs: https://docs.litellm.ai/docs/proxy/virtual_keys

Parameters:
- duration: Optional[str] - Specify the length of time the token is valid for. You can set duration as seconds ("30s"), minutes ("30m"), hours ("30h"), days ("30d").
- key_alias: Optional[str] - User defined key alias
- key: Optional[str] - User defined key value. If not set, a 16-digit unique sk-key is created for you.
- team_id: Optional[str] - The team id of the key
- user_id: Optional[str] - The user id of the key
- agent_id: Optional[str] - The agent id associated with the key.
- organization_id: Optional[str] - The organization id of the key. If not set, and team_id is set, the organization id will be the same as the team id. If conflict, an error will be raised.
- project_id: Optional[str] - The project id of the key. When set, models and max_budget are validated against the project's limits.
- budget_id: Optional[str] - The budget id associated with the key. Created by calling `/budget/new`.
- models: Optional[list] - Model_name's a user is allowed to call. (if empty, key is allowed to call all models)
- aliases: Optional[dict] - Any alias mappings, on top of anything in the config.yaml model list. - https://docs.litellm.ai/docs/proxy/virtual_keys#managing-auth---upgradedowngrade-models
- config: Optional[dict] - any key-specific configs, overrides config in config.yaml
- spend: Optional[int] - Amount spent by key. Default is 0. Will be updated by proxy whenever key is used. https://docs.litellm.ai/docs/proxy/virtual_keys#managing-auth---tracking-spend
- send_invite_email: Optional[bool] - Whether to send an invite email to the user_id, with the generate key
- max_budget: Optional[float] - Specify max budget for a given key.
- budget_duration: Optional[str] - Budget is reset at the end of specified duration. If not set, budget is never reset. You can set duration as seconds ("30s"), minutes ("30m"), hours ("30h"), days ("30d").
- max_parallel_requests: Optional[int] - Rate limit a user based on the number of parallel requests. Raises 429 error, if user's parallel requests > x.
- metadata: Optional[dict] - Metadata for key, store information for key. Example metadata = {"team": "core-infra", "app": "app2", "email": "ishaan@berri.ai" }
- guardrails: Optional[List[str]] - List of active guardrails for the key
- policies: Optional[List[str]] - List of policy names to apply to the key. Policies define guardrails, conditions, and inheritance rules.
- disable_global_guardrails: Optional[bool] - Whether to disable global guardrails for the key.
- permissions: Optional[dict] - key-specific permissions. Currently just used for turning off pii masking (if connected). Example - {"pii": false}
- model_max_budget: Optional[Dict[str, BudgetConfig]] - Model-specific budgets {"gpt-4": {"budget_limit": 0.0005, "time_period": "30d"}}}. IF null or {} then no model specific budget.
- model_rpm_limit: Optional[dict] - key-specific model rpm limit. Example - {"text-davinci-002": 1000, "gpt-3.5-turbo": 1000}. IF null or {} then no model specific rpm limit.
- model_tpm_limit: Optional[dict] - key-specific model tpm limit. Example - {"text-davinci-002": 1000, "gpt-3.5-turbo": 1000}. IF null or {} then no model specific tpm limit.
- tpm_limit_type: Optional[str] - Type of tpm limit. Options: "best_effort_throughput" (no error if we're overallocating tpm), "guaranteed_throughput" (raise an error if we're overallocating tpm), "dynamic" (dynamically exceed limit when no 429 errors). Defaults to "best_effort_throughput".
- rpm_limit_type: Optional[str] - Type of rpm limit. Options: "best_effort_throughput" (no error if we're overallocating rpm), "guaranteed_throughput" (raise an error if we're overallocating rpm), "dynamic" (dynamically exceed limit when no 429 errors). Defaults to "best_effort_throughput".
- allowed_cache_controls: Optional[list] - List of allowed cache control values. Example - ["no-cache", "no-store"]. See all values - https://docs.litellm.ai/docs/proxy/caching#turn-on--off-caching-per-request
- blocked: Optional[bool] - Whether the key is blocked.
- rpm_limit: Optional[int] - Specify rpm limit for a given key (Requests per minute)
- tpm_limit: Optional[int] - Specify tpm limit for a given key (Tokens per minute)
- soft_budget: Optional[float] - Specify soft budget for a given key. Will trigger a slack alert when this soft budget is reached.
- tags: Optional[List[str]] - Tags for [tracking spend](https://litellm.vercel.app/docs/proxy/enterprise#tracking-spend-for-custom-tags) and/or doing [tag-based routing](https://litellm.vercel.app/docs/proxy/tag_routing).
- prompts: Optional[List[str]] - List of prompts that the key is allowed to use.
- enforced_params: Optional[List[str]] - List of enforced params for the key (Enterprise only). [Docs](https://docs.litellm.ai/docs/proxy/enterprise#enforce-required-params-for-llm-requests)
- prompts: Optional[List[str]] - List of prompts that the key is allowed to use.
- allowed_routes: Optional[list] - List of allowed routes for the key. Store the actual route or store a wildcard pattern for a set of routes. Example - ["/chat/completions", "/embeddings", "/keys/*"]
- allowed_passthrough_routes: Optional[list] - List of allowed pass through endpoints for the key. Store the actual endpoint or store a wildcard pattern for a set of endpoints. Example - ["/my-custom-endpoint"]. Use this instead of allowed_routes, if you just want to specify which pass through endpoints the key can access, without specifying the routes. If allowed_routes is specified, allowed_pass_through_endpoints is ignored.
- object_permission: Optional[LiteLLM_ObjectPermissionBase] - key-specific object permission. Example - {"vector_stores": ["vector_store_1", "vector_store_2"], "agents": ["agent_1", "agent_2"], "agent_access_groups": ["dev_group"]}. IF null or {} then no object permission.
- key_type: Optional[str] - Type of key that determines default allowed routes. Options: "llm_api" (can call LLM API routes), "management" (can call management routes), "read_only" (can only call info/read routes), "default" (uses default allowed routes). Defaults to "default".
- prompts: Optional[List[str]] - List of allowed prompts for the key. If specified, the key will only be able to use these specific prompts.
- auto_rotate: Optional[bool] - Whether this key should be automatically rotated (regenerated)
- rotation_interval: Optional[str] - How often to auto-rotate this key (e.g., '30s', '30m', '30h', '30d'). Required if auto_rotate=True.
- allowed_vector_store_indexes: Optional[List[dict]] - List of allowed vector store indexes for the key. Example - [{"index_name": "my-index", "index_permissions": ["write", "read"]}]. If specified, the key will only be able to use these specific vector store indexes. Create index, using `/v1/indexes` endpoint.
- router_settings: Optional[UpdateRouterConfig] - key-specific router settings. Example - {"model_group_retry_policy": {"max_retries": 5}}. IF null or {} then no router settings.
- access_group_ids: Optional[List[str]] - List of access group IDs to associate with the key. Access groups define which models a key can access. Example - ["access_group_1", "access_group_2"].
- budget_limits: Optional[list] - List of concurrent budget windows for the key. Each window specifies a budget_limit, time_period, and optional budget_duration. Example - [{"budget_limit": 10.0, "time_period": "1d"}, {"budget_limit": 50.0, "time_period": "7d"}].

Examples:

1. Allow users to turn on/off pii masking

```bash
curl --location 'http://0.0.0.0:4000/key/generate'         --header 'Authorization: Bearer sk-1234'         --header 'Content-Type: application/json'         --data '{
        "permissions": {"allow_pii_controls": true}
}'
```

Returns:
- key: (str) The generated api key
- expires: (datetime) Datetime object for when key expires.
- user_id: (str) Unique user id - used for tracking spend across multiple keys for same user id.

## Headers

- `litellm-changed-by` string, nullable — The litellm-changed-by header enables tracking of actions performed by authorized users on behalf of other users, providing an audit trail for accountability

## Request body

- GenerateKeyRequest
  - `key_alias` string, nullable
  - `duration` string, nullable
  - `models` unknown[], nullable
    - unknown
  - `spend` number, nullable
  - `max_budget` number, nullable
  - `user_id` string, nullable
  - `team_id` string, nullable
  - `agent_id` string, nullable
  - `max_parallel_requests` integer, nullable
  - `metadata` object, nullable
  - `tpm_limit` integer, nullable
  - `rpm_limit` integer, nullable
  - `budget_duration` string, nullable
  - `budget_limits` BudgetLimitEntry[], nullable
    - `budget_duration` string, required
    - `max_budget` number, required
    - `reset_at` string, date-time, nullable
  - `allowed_cache_controls` unknown[], nullable
    - unknown
  - `config` object, nullable
  - `permissions` object, nullable
  - `model_max_budget` object, nullable
  - `model_rpm_limit` object, nullable
  - `model_tpm_limit` object, nullable
  - `guardrails` string[], nullable
  - `policies` string[], nullable
  - `prompts` string[], nullable
  - `blocked` boolean, nullable
  - `aliases` object, nullable
  - `object_permission` LiteLLMObjectPermissionBase
    - `mcp_servers` string[], nullable
    - `mcp_access_groups` string[], nullable
    - `mcp_tool_permissions` object, nullable
    - `mcp_toolsets` string[], nullable
    - `blocked_tools` string[], nullable
    - `vector_stores` string[], nullable
    - `agents` string[], nullable
    - `agent_access_groups` string[], nullable
    - `models` string[], nullable
    - `search_tools` string[], nullable
  - `key` string, nullable
  - `budget_id` string, nullable
  - `tags` string[], nullable
  - `enforced_params` string[], nullable
  - `allowed_routes` unknown[], nullable
    - unknown
  - `allowed_passthrough_routes` unknown[], nullable
    - unknown
  - `allowed_vector_store_indexes` AllowedVectorStoreIndexItem[], nullable
    - `index_name` string, required
    - `index_permissions` string[], required
  - `rpm_limit_type` 'guaranteed_throughput' | 'best_effort_throughput' | 'dynamic', nullable
  - `tpm_limit_type` 'guaranteed_throughput' | 'best_effort_throughput' | 'dynamic', nullable
  - `router_settings` UpdateRouterConfig — Set of params that you can modify via `router.update_settings()`.
    - `routing_strategy_args` object, nullable
    - `routing_strategy` string, nullable
    - `routing_groups` RoutingGroup[], nullable
      - `group_name` string, required
      - `models` string[], required
      - `routing_strategy` string, required
      - `routing_strategy_args` object, nullable
    - `model_group_retry_policy` object, nullable
    - `model_group_affinity_config` object, nullable
    - `allowed_fails` integer, nullable
    - `cooldown_time` number, nullable
    - `num_retries` integer, nullable
    - `timeout` number, nullable
    - `max_retries` integer, nullable
    - `retry_after` number, nullable
    - `fallbacks` object[], nullable
    - `context_window_fallbacks` object[], nullable
    - `model_group_alias` object, nullable
  - `access_group_ids` string[], nullable
  - `soft_budget` number, nullable
  - `send_invite_email` boolean, nullable
  - `key_type` 'llm_api' | 'management' | 'read_only' | 'default' — Enum for key types that determine what routes a key can access
  - `auto_rotate` boolean, nullable — Whether this key should be automatically rotated
  - `rotation_interval` string, nullable — How often to rotate this key (e.g., '30d', '90d'). Required if auto_rotate=True
  - `organization_id` string, nullable
  - `project_id` string, nullable

## Response `200`

Successful Response

- GenerateKeyResponse
  - `key_alias` string, nullable
  - `duration` string, nullable
  - `models` unknown[], nullable
    - unknown
  - `spend` number, nullable
  - `max_budget` number, nullable
  - `user_id` string, nullable
  - `team_id` string, nullable
  - `agent_id` string, nullable
  - `max_parallel_requests` integer, nullable
  - `metadata` object, nullable
  - `tpm_limit` integer, nullable
  - `rpm_limit` integer, nullable
  - `budget_duration` string, nullable
  - `budget_limits` BudgetLimitEntry[], nullable
    - `budget_duration` string, required
    - `max_budget` number, required
    - `reset_at` string, date-time, nullable
  - `allowed_cache_controls` unknown[], nullable
    - unknown
  - `config` object, nullable
  - `permissions` object, nullable
  - `model_max_budget` object, nullable
  - `model_rpm_limit` object, nullable
  - `model_tpm_limit` object, nullable
  - `guardrails` string[], nullable
  - `policies` string[], nullable
  - `prompts` string[], nullable
  - `blocked` boolean, nullable
  - `aliases` object, nullable
  - `object_permission` LiteLLMObjectPermissionBase
    - `mcp_servers` string[], nullable
    - `mcp_access_groups` string[], nullable
    - `mcp_tool_permissions` object, nullable
    - `mcp_toolsets` string[], nullable
    - `blocked_tools` string[], nullable
    - `vector_stores` string[], nullable
    - `agents` string[], nullable
    - `agent_access_groups` string[], nullable
    - `models` string[], nullable
    - `search_tools` string[], nullable
  - `key` string, required
  - `budget_id` string, nullable
  - `tags` string[], nullable
  - `enforced_params` string[], nullable
  - `allowed_routes` unknown[], nullable
    - unknown
  - `allowed_passthrough_routes` unknown[], nullable
    - unknown
  - `allowed_vector_store_indexes` AllowedVectorStoreIndexItem[], nullable
    - `index_name` string, required
    - `index_permissions` string[], required
  - `rpm_limit_type` 'guaranteed_throughput' | 'best_effort_throughput' | 'dynamic', nullable
  - `tpm_limit_type` 'guaranteed_throughput' | 'best_effort_throughput' | 'dynamic', nullable
  - `router_settings` UpdateRouterConfig — Set of params that you can modify via `router.update_settings()`.
    - `routing_strategy_args` object, nullable
    - `routing_strategy` string, nullable
    - `routing_groups` RoutingGroup[], nullable
      - `group_name` string, required
      - `models` string[], required
      - `routing_strategy` string, required
      - `routing_strategy_args` object, nullable
    - `model_group_retry_policy` object, nullable
    - `model_group_affinity_config` object, nullable
    - `allowed_fails` integer, nullable
    - `cooldown_time` number, nullable
    - `num_retries` integer, nullable
    - `timeout` number, nullable
    - `max_retries` integer, nullable
    - `retry_after` number, nullable
    - `fallbacks` object[], nullable
    - `context_window_fallbacks` object[], nullable
    - `model_group_alias` object, nullable
  - `access_group_ids` string[], nullable
  - `key_name` string, nullable
  - `expires` string, date-time, nullable
  - `token_id` string, nullable
  - `organization_id` string, nullable
  - `project_id` string, nullable
  - `litellm_budget_table` unknown
  - `token` string, nullable
  - `created_by` string, nullable
  - `updated_by` string, nullable
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/flock/apis/litellm-api.md) · [All operations](https://skmtc.net/flock/apis/litellm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flock/litellm-api/revisions/8fbaab4fc7c5/schema)