docs(proxy): document the unified custom_key_policy key hook

[mateo-berri]

TLDR

Documents the new general_settings.custom_key_policy hook for proxy virtual keys: one policy function that runs on every key operation (/key/generate, /key/service-account/generate, /key/update, /key/bulk_update, /team/key/bulk_update, and /key/{key}/regenerate, so every Admin UI create, edit, and regenerate flow) and receives the operation plus the effective key state, meaning the existing key merged with the requested changes with a relative duration already turned into an absolute expires. The new section in the virtual keys page explains the policy_request contract (operation, existing_key, effective_key, request), the {"decision", "message"} return shape and its 403, where in the request path the hook runs, and that the legacy custom_key_generate and custom_key_update hooks keep working unchanged and run first when also configured, with a worked example that caps every key at seven days. The two legacy sections now point at it as the recommended single hook, and the config settings table gains a custom_key_policy row. It pairs with the litellm code PR on branch litellm_unified_key_policy_hook; the code PR is being opened separately, and this docs PR merges after it lands

Linear ticket

Resolves LIT-7524

Preview

docs/proxy/virtual_keys.md gains the "Custom key policy (one hook for every key operation)" section between "Custom /key/update" and "Upperbound /key/generate params", plus one pointer sentence in each of the two legacy hook sections. docs/proxy/config_settings.md gains the custom_key_policy row right after custom_key_update in the general_settings table, linking to the new section

---

Note

Low Risk
Documentation-only change with no runtime or configuration behavior in this PR.

Overview
Adds documentation for general_settings.custom_key_policy, a unified virtual-key policy hook that runs on generate, update, and regenerate with the effective merged key state (including absolute expires from relative duration).

docs/proxy/virtual_keys.md gains a full section covering the policy_request contract (operation, existing_key, effective_key, request), the {"decision", "message"} / 403 behavior, covered routes (including Admin UI flows), ordering when used with custom_key_generate and custom_key_update, and a seven-day expiry example. The legacy generate/update sections and their warning now point readers to this hook as the recommended approach.

docs/proxy/config_settings.md adds a custom_key_policy row to the general_settings reference table, linked to the new section.

^{Reviewed by Cursor Bugbot for commit 396ce5e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
litellm	Ready	Preview	Sep 12, 2026 10:21pm UTC

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 396ce5e. Configure here.}