docs(proxy): say how spend logs record which requests a client-forwarded OAuth token paid for

[mateo-berri]

TLDR

Documents the metadata.used_client_oauth_token spend log flag that BerriAI/litellm#43063 adds, so an admin whose developers run Claude Code on Max seats through the gateway can tell which requests a seat paid for and which ones the deployment's configured key paid for. The code is in main and first shipped in v1.105.0-rc.1 (Sat, Oct 3); stable v1.105.0 is not cut yet, so the docs name v1.105.0 as the first release with the flag

User Flow

Before: the admin reads the Max subscription tutorial and finds no way to split seat-billed requests from key-billed ones, so the API bill they reconcile from the logs stays wrong

1. The admin opens https://docs.litellm.ai/docs/tutorials/claude_code_max_subscription to reconcile the Anthropic API bill against the gateway logs
2. They read Budget Controls and then Troubleshooting: nothing says which spend log rows a Max seat paid for
3. They open https://docs.litellm.ai/docs/proxy/forward_client_headers: the Claude Code paragraph explains that /login forwards an OAuth token, but says nothing about how that shows up in the logs
4. They guess at a filter on GET https://litellm-domain/spend/logs/ui and have no documented parameter to pass

After: the admin finds a section that names the flag, the Logs page filter, and the API parameter, and gets the seat-billed rows on the first try

1. The admin opens https://docs.litellm.ai/docs/tutorials/claude_code_max_subscription to reconcile the Anthropic API bill against the gateway logs
2. Under Advanced Configuration they read "Seeing Which Requests Were Billed to a Seat": metadata.used_client_oauth_token is true for a forwarded OAuth token and false for the configured key, it needs v1.105.0 or later, Bedrock and Vertex routes read false, and spend stays at list price, so they subtract the seat-billed rows
3. They open https://litellm-domain/ui/?page=logs, pick Client OAuth token in the Credential filter, and see only the seat-billed rows, each drawer showing Credential under Request Details
4. They send GET https://litellm-domain/spend/logs/ui?used_client_oauth_token=true with Authorization: Bearer <admin key> and get back 200 with only those rows; used_client_oauth_token=false returns the key-billed ones
5. On https://docs.litellm.ai/docs/proxy/forward_client_headers the Claude Code paragraph names the same flag and both filters

Changes

• docs/tutorials/claude_code_max_subscription.md gains a section on listing the requests a Max seat paid for, on the Logs page and with GET /spend/logs/ui?used_client_oauth_token=true, names v1.105.0 as the first release with the flag, and says spend stays at list price so reporting subtracts those rows
• docs/proxy/forward_client_headers.md names the flag and its filters next to the OAuth forwarding paragraph

Checks

node scripts/check-writing-style.js docs blog release_notes and python3 scripts/check-docs.py docs both pass locally at the tip after merging main. Every claim was checked against litellm main at aa64b07281: the used_client_oauth_token query parameter on /spend/logs/ui, the Credential filter and drawer labels (Client OAuth token, Configured key), the flag resolving to false for any provider other than direct Anthropic, and no spend change on seat-billed rows

Caveats

Low: "Every spend log row" was checked for the unified /v1/messages, /v1/chat/completions and /v1/responses routes this tutorial uses, not for the /anthropic pass-through route, whose rows may carry no value. Left as is, since chasing it needs a live pass-through run for a route the tutorial never sends to

Screenshots / Proof of Fix

Rendered pages at 1280x900: before is https://docs.litellm.ai (built from main), after is this PR's Vercel preview at 89a6a39c. To reproduce, open /docs/tutorials/claude_code_max_subscription and scroll to the end of Advanced Configuration, then open /docs/proxy/forward_client_headers and find the Claude Code paragraph under "Use Case: Client-Side API Keys (BYOK)"

Before, Budget Controls runs straight into Troubleshooting and nothing says which rows a Max seat paid for

After, "Seeing Which Requests Were Billed to a Seat" sits between them with the flag, the v1.105.0 floor, the Credential filter, and the curl

After, the Claude Code paragraph on the forward headers page names the same flag and filters (the production page has no mention of used_client_oauth_token)

The release claim was checked against tags: v1.105.0-rc.1 carries the used_client_oauth_token query parameter and the Client OAuth token / Configured key labels, and v1.104.2, the newest stable, carries neither. The live behavior the section describes (seat rows true, configured-key rows false, spend unchanged, ?used_client_oauth_token=true returning only seat rows) is the Claude Code proof on BerriAI/litellm#43063

• 89a6a39 passes /live-pr-risk (no surface: docs-only, no litellm code changed)

---

Note

Low Risk
Documentation-only changes with no runtime or security behavior modifications.

Overview
Documents metadata.used_client_oauth_token on spend logs so operators can tell whether upstream Anthropic was billed via a forwarded client OAuth token or the deployment’s configured API key (the token itself is never logged).

docs/tutorials/claude_code_max_subscription.md adds Seeing Which Requests Were Billed to a Seat: meaning of the flag (including Bedrock/Vertex routes as false), that spend stays at list price for budgets while real API cost requires subtracting seat-billed rows, and how to filter in the Logs Credential dropdown or with GET /spend/logs/ui?used_client_oauth_token=true|false.

docs/proxy/forward_client_headers.md extends the Claude Code OAuth forwarding note with the same metadata field and filter options.

^{Reviewed by Cursor Bugbot for commit 5bce11f. 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	Oct 9, 2026 9:52pm UTC

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[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 89a6a39. Configure here.}