# LiteLLM virtual keys: separate access for each application

Give each LiteLLM application a scoped virtual key with documented models, ownership, budget rules, revocation and persistence checks.

Author: Retrivium team
Updated: 2026-11-01
Canonical URL: https://retrivium.ai/journal/litellm-virtual-key-scopes/
Language: en

A LiteLLM virtual key separates one application's access from another without distributing the administrative master key. Define allowed models, ownership, spending controls and revocation first. Verify the effective restrictions through controlled calls rather than assuming a saved key proves its policy is active.

## Confirm the stateful mode

LiteLLM documents database requirements for virtual-key management. Check that the gateway uses the required storage and preserves records after restart. A minimal proxy accepting a master key does not establish a working key-management system with every intended feature.

Save the gateway version, database setup and credential ownership without copying secrets into deployment notes. Confirm the intended instance and environment before issuing client access. Similar ports or dashboard titles can otherwise cause an operator to configure another gateway. A short control request helps associate the UI with the actual serving process.

## Specify application rights

| Property | Decision before issuance |
| --- | --- |
| Models | Configured names the client may request |
| Owner and team | Purpose and organizational responsibility |
| Spending and frequency | Restrictions that actually apply |
| Lifetime | Expiry or review date |
| Administration | Whether any management operation is needed |

A descriptive application name is not an enforced scope. Inspect configuration and test a permitted model alongside a deliberately excluded one. The negative case should remain within the authorized pilot and produce an understandable failure. Do not give a client broad administrative access merely to simplify an initial demonstration.

## Check the applicable budget

Key, user and team controls are not independent identical wallets. Check the rule for the key's association. Current documentation states that a key with `team_id` does not use the owner's personal budget; team and applicable team-member budgets govern instead.

Preserve the installed version and the observed rule. Record which counter changes after a small request and which boundary rejects a controlled over-limit attempt. Do not add several entity limits into an imaginary available balance. Usage accounting must work before its budget result can be interpreted.

## Test revocation and upgrades

Revoke a separate test key and confirm the old access stops working. Verify that unrelated applications retain their intended permissions. Keep an inventory of owners and dependent jobs so rotation is a planned update rather than a surprise outage.

Repeat these checks after an upgrade, model rename or budget change. A hardware owner gains a clear application boundary; an operations partner sees the management work still required.

Official references: [docs.litellm.ai — virtual keys](https://docs.litellm.ai/docs/proxy/virtual_keys), [docs.litellm.ai — users](https://docs.litellm.ai/docs/proxy/users).

Related guides: [Starting a LiteLLM gateway with Docker Compose](/journal/litellm-docker-compose-start/), [LiteLLM budgets: periods, shared limits and overrun tests](/journal/litellm-budget-reset/).