feat(team): custom metadata validation hook for team create and update

[yuneng-berri]

Relevant issues

Linear ticket

Resolves LIT-3979

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

Captured at commit b67cdb6 against a live proxy (port 4010) backed by Postgres, no mocks. The proxy was started with this config:

general_settings:
  master_key: sk-1234
  custom_team_metadata_validate: qa_team_metadata_validator.validate_team_metadata
  team_metadata_validation_timeout: 5
  team_metadata_validation_error_message: "Cost center validation is unavailable right now; the team was not saved. Contact FinOps."

and this validator next to it, which accepts cost centers CC-1001/CC-1002, rejects everything else with a specific message, and raises on CC-KABOOM to simulate the operator's upstream service being down:

from litellm.proxy.management_helpers.team_metadata_validation import (
    TeamMetadataValidationPayload,
    TeamMetadataValidationResult,
)

VALID_COST_CENTERS = {"CC-1001", "CC-1002"}

async def validate_team_metadata(payload: TeamMetadataValidationPayload) -> TeamMetadataValidationResult:
    cost_center = payload.metadata.get("cost_center")
    if cost_center == "CC-KABOOM":
        raise RuntimeError("simulated internal validation service outage")
    if cost_center is None:
        return TeamMetadataValidationResult(valid=False, error_message="Team metadata must include a cost_center. Contact the FinOps team.")
    if cost_center not in VALID_COST_CENTERS:
        return TeamMetadataValidationResult(valid=False, error_message=f"Cost center {cost_center} is not recognized. Contact the FinOps team.")
    return TeamMetadataValidationResult(valid=True)

1. Create with a valid cost center succeeds

$ curl -sS -X POST 'http://localhost:4010/team/new' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_alias": "qa-valid-team", "team_id": "qa-team-valid-1", "metadata": {"cost_center": "CC-1001"}}'
{"team_alias":"qa-valid-team","team_id":"qa-team-valid-1",...,"metadata":{"cost_center":"CC-1001"},...}

2. Create with an unrecognized cost center is blocked with the validator's own message

$ curl -sS -X POST 'http://localhost:4010/team/new' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_alias": "qa-bad-team", "metadata": {"cost_center": "CC-9999"}}'
{"error":{"message":"{'error': 'Cost center CC-9999 is not recognized. Contact the FinOps team.'}","type":"internal_server_error","param":"None","code":"400"}}

3. Create with no metadata at all still validates, so a required key can be enforced

$ curl -sS -X POST 'http://localhost:4010/team/new' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_alias": "qa-no-meta-team"}'
{"error":{"message":"{'error': 'Team metadata must include a cost_center. Contact the FinOps team.'}","type":"internal_server_error","param":"None","code":"400"}}

4. A raising validator fails closed with the configured generic message as a 503

$ curl -sS -X POST 'http://localhost:4010/team/new' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_alias": "qa-outage-team", "metadata": {"cost_center": "CC-KABOOM"}}'
{"error":{"message":"{'error': 'Cost center validation is unavailable right now; the team was not saved. Contact FinOps.'}","type":"internal_server_error","param":"None","code":"503"}}

5. PATCH of an unrelated metadata key validates the merged result, so the preserved cost center passes

$ curl -sS -X PATCH 'http://localhost:4010/team/qa-team-valid-1' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"metadata": {"team_notes": "hello"}}'
{"team_alias":"qa-valid-team","team_id":"qa-team-valid-1",...,"metadata":{"team_notes":"hello","cost_center":"CC-1001"},...}

6. Deleting the required key via PATCH null is caught, because the validator sees the key's absence in the merged result

$ curl -sS -X PATCH 'http://localhost:4010/team/qa-team-valid-1' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"metadata": {"cost_center": null}}'
{"error":{"message":"{'error': 'Team metadata must include a cost_center. Contact the FinOps team.'}","type":"internal_server_error","param":"None","code":"400"}}

7. POST /team/update replacing metadata wholesale without the required key is caught the same way

$ curl -sS -X POST 'http://localhost:4010/team/update' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_id": "qa-team-valid-1", "metadata": {"team_notes": "only-notes"}}'
{"error":{"message":"{'error': 'Team metadata must include a cost_center. Contact the FinOps team.'}","type":"internal_server_error","param":"None","code":"400"}}

8. An update that does not touch metadata skips validation and succeeds

$ curl -sS -X POST 'http://localhost:4010/team/update' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_id": "qa-team-valid-1", "tpm_limit": 50}'
{"team_id":"qa-team-valid-1","data":{...}}

9. A rejected create leaves no row behind

$ curl -sS -X POST 'http://localhost:4010/team/new' ... -d '{"team_alias": "qa-reject-rowcheck", "team_id": "qa-team-rejected-1", "metadata": {"cost_center": "CC-9999"}}'   # rejected with 400
$ curl -sS 'http://localhost:4010/team/info?team_id=qa-team-rejected-1' -H 'Authorization: Bearer sk-1234'
{"error":{"message":"{'message': 'Team not found, passed team id: qa-team-rejected-1.'}","type":"auth_error","param":"None","code":"404"}}

10. The blocked deletes in 6 and 7 left the stored metadata intact

$ curl -sS 'http://localhost:4010/team/info?team_id=qa-team-valid-1' -H 'Authorization: Bearer sk-1234' | python -c "import json,sys; print(json.load(sys.stdin)['team_info']['metadata'])"
{'team_notes': 'hello', 'cost_center': 'CC-1001'}

Review follow-ups (commit 93d802c)

Both bot findings were confirmed and fixed. Validation now runs before the model_aliases table insert, so a rejected create can no longer leave an orphaned LiteLLM_ModelTable row (regression test asserts the model create mock is never awaited on rejection). The payload's existing_metadata now has system-managed keys stripped from a copy, matching the stripped metadata field, so a key-preservation validator never sees server-owned keys like team_member_budget_id "disappear" on PATCH. The remaining Greptile note about a validator's own HTTPException being converted to the generic 503 describes the intended fail-closed contract: validators signal rejections by returning valid=False with their message, and any raise is treated as a system failure

The runner also accepts class instances exposing an async call (the natural shape for a validator holding an HTTP client), which previously failed the coroutine check

This commit adds a validator implementation matrix: three independent implementations (a static allowlist function, an HTTP-service-backed function using httpx against a stub cost center service, and an immutability-enforcing class instance that uses existing_metadata) each driven through the real /team/new, POST /team/update, and PATCH /team/{team_id} paths across 8 scenarios, plus service-outage coverage for the HTTP implementation. The same three implementations were also exercised against a live DB-backed proxy via config, with results matching the test matrix cell for cell

DB-backed proxy e2e in CI (commit f240a58)

The validator matrix now also runs full e2e against a Postgres-backed proxy in the existing proxy_store_model_in_db_tests CircleCI job. The job's config (store_model_db_config.yaml) registers team_metadata_validator_e2e.validate_team_metadata, a dispatching validator mounted next to the config in the container; it routes each request to one of the three implementations via a _e2e_validator_impl metadata key and accepts any request that does not carry the key, so the suite's other team operations are unaffected. CI starts a stand-in cost center service on the host (tests/store_model_in_db_tests/cost_center_service.py, port 9414) which the HTTP-backed implementation reaches through host.docker.internal, mirroring how the job already runs its fake OpenAI endpoint; the outage scenario targets a closed port so the fail-closed 503 is proven without stopping services. The job already passes LITELLM_LICENSE, which this premium-gated feature requires

tests/store_model_in_db_tests/test_team_metadata_validation_e2e.py holds the matrix: 8 scenarios x 3 implementations plus the outage case and a no-dispatch-key control, asserting status codes, the validator-authored messages, that a rejected create leaves no team row, and that a blocked update leaves stored metadata intact. The full file was verified locally against a DB-backed proxy started with the same config and mounted validator (26/26 passed) before wiring it into CI

Admin UI: metadata as key-value pairs (commit eda8491)

The team create and edit forms previously asked for metadata as raw JSON in a textarea buried inside Additional Settings, so a malformed blob failed in the browser before the validator ever saw it and admins had to hand-write JSON for what is conceptually a set of key-value pairs. Both forms now render a key-value pair editor directly under the TPM/RPM limit fields, backed by a new shared MetadataKeyValueFields component. Values accept plain text or JSON: non-string values display as JSON and parse back to their typed form on save, and JSON-ambiguous strings are quoted on display so types survive the round trip. The edit form hides UI-managed keys (logging, guardrails, model rate limits and similar) that dedicated controls already own and re-add on save

Verified end to end at eda8491 with the dashboard dev server against a live Dockerized proxy on localhost:4000 running this PR's allowlist cost center validator (accepts CC-1001/CC-1002):

1. Teams -> Create Team: fill Team Name and Models, add the pair cost_center / CC-9999 in the Metadata editor under the RPM field, submit; the create is blocked and the toast carries the validator's own message: Error creating the team: ApiError: {'error': 'Cost center CC-9999 is not recognized. Contact the FinOps team.'}
2. Change the value to CC-1001 and resubmit; the team is created and GET /team/list shows metadata {"cost_center": "CC-1001"} stored as a typed object
3. Open the team, Settings tab, Edit Settings: the pair prefills as cost_center / CC-1001 under the RPM field, and UI-managed keys do not appear as editable pairs
4. Change the value to CC-9999 and Save Changes; the update is blocked with the same validator message and the form stays open for correction
5. Change the value to CC-1002 and save; GET /team/info confirms cost_center is now CC-1002 while the UI-managed keys are untouched

Before/after screenshots (before: the JSON textarea inside Additional Settings at f240a58; after: the pair editor under the RPM field at eda8491) reproduce from http://localhost:3000/teams via Create Team for the create modal and via any team's Settings -> Edit Settings for the edit form, with the proxy from the QA config above on localhost:4000

Schema-prepopulated metadata fields (commits 19c2577 through eea99b3)

Customer feedback on the dev image was that users filling in team metadata have no indication of which keys are expected or how they are named (cost_center vs CostCenter vs costcenter). These commits add a declarative team_metadata_schema in config that the UI uses to prepopulate the metadata editor, and clean up how a validator rejection is shown to the user. Each schema field is a key plus an optional display label. Verified at 698bc8a against a live DB-backed proxy running both the schema and this PR's cost center validator:

general_settings:
  master_key: sk-1234
  custom_team_metadata_validate: qa_team_metadata_validator.validate_team_metadata
  team_metadata_validation_timeout: 5
  team_metadata_validation_error_message: "Cost center validation is unavailable right now; the team was not saved. Contact FinOps."
  team_metadata_schema:
    - key: cost_center
      label: "Cost Center"
    - key: app_name
      label: "Application Name"
    - key: chargeback_mode
      label: "Chargeback Mode"

1. The new endpoint serves the declared fields to authenticated callers

$ curl -sS 'http://localhost:4000/team/metadata_schema' -H 'Authorization: Bearer sk-1234'
{"fields":[{"key":"cost_center","label":"Cost Center"},{"key":"app_name","label":"Application Name"},{"key":"chargeback_mode","label":"Chargeback Mode"}]}

2. The endpoint requires auth; the schema is org-internal and deliberately not on the unauthenticated well-known UI config

$ curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:4000/team/metadata_schema
401
$ curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:4000/team/metadata_schema -H 'Authorization: Bearer sk-wrong'
401

3. The schema and the validator compose: the same proxy rejects a create whose cost center the validator does not know, with the validator's own message and no row written

$ curl -sS -X POST 'http://localhost:4000/team/new' -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
    -d '{"team_alias": "qa-reject-check", "metadata": {"cost_center": "CC-9999"}}'
{"error":{"message":"{'error': 'Cost center CC-9999 is not recognized. Contact the FinOps team.'}","type":"internal_server_error","param":"None","code":"400"}}

4. With no schema configured the endpoint returns an empty list, which the UI renders as the plain free-form editor, so nothing changes for proxies that do not opt in

$ curl -sS 'http://localhost:4042/team/metadata_schema' -H 'Authorization: Bearer sk-1234'
{"fields":[]}

5. A malformed schema fails proxy startup instead of silently serving a broken form (unknown field names are rejected)

$ python litellm/proxy/proxy_cli.py --config bad_schema_config.yaml --port 4043; echo "exit code: $?"
pydantic_core._pydantic_core.ValidationError: 1 validation error for tuple[TeamMetadataFieldSchema, ...]
  Extra inputs are not permitted [type=extra_forbidden, input_value=True, input_type=bool]
exit code: 3

UI screenshots reproduce from http://localhost:3000/teams with the dev server pointed at a proxy running the config above:

1. Click Create Team and scroll to Metadata: each declared key is prepopulated as an ordinary key-value pair row, exactly as if it had been added with the Add Key-Value Pair button, with the key filled in; rows stay fully editable and removable
2. Enter CC-9999 as the cost center and submit: the server-side validator rejects it and the toast reads "Error creating the team: Cost center CC-9999 is not recognized. Contact the FinOps team." with no ApiError or JSON wrapper around the message
3. Change to CC-1001 and create, then open the team, Settings, Edit Settings: cost_center shows as a prefilled pair row alongside any other stored keys, and declared keys missing from the stored metadata are appended as empty rows; a rejected save shows the same clean message via "Failed to update team settings: ..."
4. Add another row and give it the key cost_center: the ordinary duplicate-key validation rejects it
5. Fill Application Name and save, then blank it and save again: the key appears in stored metadata after the first save and is gone after the second, since blank fields are omitted rather than saved as empty strings
6. Remove team_metadata_schema from the config, restart the proxy, and reopen either modal: the plain free-form editor is back, and any metadata keys the schema used to own reappear as ordinary editable rows

Type

🆕 New Feature

Changes

Operators can now require and validate custom team metadata (for example a cost center that must exist in an internal system of record) by pointing the proxy config at their own async Python function, following the same config surface as custom_key_generate:

general_settings:
  custom_team_metadata_validate: my_module.validate_team_metadata
  team_metadata_validation_timeout: 5              # optional, seconds, default 5
  team_metadata_validation_error_message: "..."    # optional, generic fail-closed message

The function receives a typed TeamMetadataValidationPayload (operation, the metadata that will actually be written, the stored metadata, team id/alias, and requester identity) and returns a TeamMetadataValidationResult. Returning valid=False blocks the write with the function's error_message as a 400. Any raised exception, timeout, or malformed return fails closed with the configurable generic message as a 503, so an unreachable upstream validation service can never let an unvalidated team through

The hook gates every team write path: POST /team/new (always, even when no metadata is sent, so a required key can be enforced at creation), POST /team/update, and PATCH /team/{team_id} (only when the request carries metadata; the validator sees the RFC 7386 merged result on PATCH and the replacement on POST). It runs before any side effects, so a rejected write leaves no rows behind. The loaded validator lives in a small registry object rather than a new module global, and the new config key is registered alongside the sibling custom hook keys in the DB-overlay config handling for consistent behavior

The feature is premium-gated, matching enforced_params. An example validator is included at litellm/proxy/example_config_yaml/custom_team_metadata_validate.py

New files: litellm/proxy/management_helpers/team_metadata_validation.py plus its mapped test file. Touched: proxy_server.py (config load), team_endpoints.py (two call sites), and the team endpoint tests

The Admin UI now edits team metadata as key-value pairs in both the team create and edit forms, placed directly under the TPM/RPM limit fields instead of a JSON textarea inside Additional Settings. A shared MetadataKeyValueFields component owns the pair rows and the object/pairs conversion, values may be plain text or JSON and round-trip losslessly, and the edit form filters out UI-managed metadata keys that dedicated controls re-add on save. Touched: Teams.tsx and team/TeamInfo.tsx plus their mapped test files, and the new component with its own test file

Building on the validator, operators can now declare the expected team metadata keys in general_settings.team_metadata_schema (each entry is a key plus an optional display label). A new authenticated GET /team/metadata_schema endpoint serves the declaration; the config is parsed with pydantic at load, so an unknown field name, a missing or empty key, or duplicate keys fail proxy startup. The schema is advisory and display-only; enforcement stays entirely with custom_team_metadata_validate

In both team modals, declared keys are prepopulated into the ordinary key-value editor as if the user had added the rows themselves: the key input is prefilled with the declared key and the rows stay fully editable and removable. Keys already present in the stored metadata are not duplicated, and deleting or renaming a prepopulated row behaves exactly like any hand-added row. The dashboard fetches the schema when the Teams page mounts (react-query, 24 hour staleTime matching the well-known UI config, retry 1, since config changes require a restart anyway) and shows a skeleton in the metadata section while the fetch is in flight. On any fetch error the modals silently fall back to the free-form editor with no toast or console noise: the server-side validator still fails closed, so a degraded UI can never let invalid metadata through, and a proxy without the endpoint or schema behaves exactly as before

The endpoint is registered in the info route group alongside /team/info and /team/available (commit 0d0b486), so team admins and internal users editing their team see the prepopulated keys too; without this the route classified as admin-only management and non-admin dashboard sessions got a 401, which the fail-open path silently turned into a plain free-form editor. Found by a live-key test matrix; pinned by a route-group membership test and a TestClient auth test

The validation module was also mutation tested (mutmut, 114 mutants): the five initial survivors exposed a missing timeout boundary case, untested effective-timeout wiring, and loose error-message assertions, and eea99b3 adds tests that bring the module to a 100 percent kill rate

Validator rejections now surface cleanly in the UI. The proxy serializes an HTTPException detail as the string form of a Python dict, so the browser previously toasted "Error creating the team: ApiError: {'error': ...}" on create and the whole raw JSON envelope on update. A new unwrapProxyErrorMessage helper in the shared http client unwraps both shapes down to the validator's own message, and the create and update toasts use it

New files: the TeamMetadataFieldSchema/TeamMetadataSchemaResponse types, parse_team_metadata_schema plus a schema registry in team_metadata_validation.py, the useTeamMetadataSchema react-query hook, and their mapped test files. Touched: proxy_server.py (config load), team_endpoints.py (the GET route), MetadataKeyValueFields.tsx (schema rows, skeleton, free-form guard), both team modals, the shared http client error helpers, and the regenerated dashboard API types

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[greptile-apps]

Greptile Summary

This PR adds a custom_team_metadata_validate hook that gates every team write path (POST /team/new, POST /team/update, PATCH /team/{team_id}) with an operator-supplied async validator, following the same config surface and registry pattern as custom_key_generate. It also introduces a team_metadata_schema config that prepopulates the metadata editor in both team modals, and replaces the raw-JSON textarea in those modals with a key-value pair editor backed by a new MetadataKeyValueFields component.

• Backend: Validation runs before any DB side effects (model table insert, team table create/update), with system-managed metadata keys stripped from both metadata and existing_metadata before the validator sees them. A rejected call returns HTTP 400 with the validator's own message; any raised exception or timeout fails closed as HTTP 503 with a configurable generic message. The premium gate, registry reset on config reload, and DB-overlay config registration all match the sibling hook patterns.
• Frontend: The pair editor supports plain-text and JSON-typed values with lossless round-tripping, schema-declared keys are prepopulated as ordinary editable rows, and validator rejections are now surfaced as the validator's own message rather than the raw JSON envelope via unwrapProxyErrorMessage.
• Tests: A 704-line unit test file with mutation-tested coverage, a validator implementation matrix tested against live endpoints, and a CircleCI e2e job covering DB-backed scenarios.

Confidence Score: 5/5

Safe to merge; the validation hook is additive and opt-in, all write paths fail closed, and existing teams without the config key are completely unaffected.

The core validation logic, registry/cleanup plumbing, and UI changes are all correct and well-tested. The only finding is that the HTTP-backed validator scenarios in the matrix test start a real ThreadingHTTPServer and make live httpx calls, which is a policy mismatch for the tests/test_litellm/ folder but does not affect production behavior or other tests.

Files Needing Attention: tests/test_litellm/proxy/management_helpers/test_team_metadata_validation.py — the matrix test scenarios for the HTTP implementation use real socket I/O and should be moved or mocked.

Important Files Changed

Filename	Overview
litellm/proxy/management_helpers/team_metadata_validation.py	New module implementing the custom team metadata validation hook; fail-closed design, registry pattern, schema parsing, and timeout/unavailable-message helpers all look correct
litellm/proxy/management_endpoints/team_endpoints.py	Validation inserted at the right points (before any DB side effects on create; on update/patch when metadata is present); system-managed key stripping applied to both metadata and existing_metadata before the validator call
litellm/proxy/proxy_server.py	Validator and schema registries are loaded and reset correctly alongside sibling hooks; new config key registered in DB-overlay remote module string fields for consistent behavior
tests/test_litellm/proxy/management_helpers/test_team_metadata_validation.py	Comprehensive test coverage including a validator implementation matrix, but the matrix tests for the HTTP-backed implementation start a real ThreadingHTTPServer and make real httpx connections, violating the no-network-calls policy for this test folder
ui/litellm-dashboard/src/lib/http/client.ts	unwrapProxyErrorMessage and extractProxyErrorMessage helpers correctly peel the Python-dict-string wrapper from proxy error responses; recursive JSON unwrap terminates because the derived-equals-trimmed check prevents re-parsing the same value
ui/litellm-dashboard/src/components/common_components/MetadataKeyValueFields.tsx	New shared component for key-value pair metadata editing; schema prepopulation, JSON round-trip, and skeleton loading state all look correct

_{Reviews (5): Last reviewed commit: "fix(proxy): use pooled async httpx clien..." | Re-trigger Greptile}

[veria-ai]

PR overview

This PR adds a custom validation hook for team metadata during team creation and updates in the proxy management endpoints. It focuses on applying configured metadata rules as team records are created or modified.

There is one remaining issue: some metadata-backed team fields can still be supplied outside the explicit metadata object and persisted after validation runs, allowing a team admin to bypass the configured metadata policy. One issue has already been addressed, so the PR is moving in the right direction, but the remaining gap affects the core validation behavior this change introduces. The risk is limited by requiring team-admin-level action, but it can still result in policy-violating team metadata being saved.

Open issues (1)

• Medium: Metadata fields bypass validation — litellm/proxy/management_endpoints/team_endpoints.py:1143

Fixed/addressed: 1 · PR risk: 5/10

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_/bold-mclaren-8d89b3 (bb645aa) with litellm_internal_staging (ba1bde7)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (c6a796a) during the generation of this report, so ba1bde7 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[codecov]

Codecov Report

❌ Patch coverage is 87.32394% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...oxy/management_helpers/team_metadata_validation.py	88.78%	12 Missing ⚠️
...tellm/proxy/management_endpoints/team_endpoints.py	72.22%	5 Missing ⚠️
litellm/proxy/proxy_server.py	90.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[veria-ai]

Medium: Metadata fields bypass validation

A team admin can bypass the configured metadata policy by supplying top-level fields such as tags, allowed_passthrough_routes, or secret_manager_settings. These values are added to the persisted metadata later at lines 1202–1217, after this validation has completed. The update path validates before _update_metadata_fields(), and skips the validator entirely when no explicit metadata key is supplied. Materialize all metadata-backed fields first, then validate the final dictionary that will be written.

[yuneng-berri]

@greptile

[yuneng-berri]

@greptile review again with the UI changes

[yuneng-berri]

@greptile review again with the latest changes

[devin-ai-integration]

QA of the team metadata validation hook, the schema, and the Admin UI editor

Ran the full happy / sad / edge matrix at be8ac082c7 against a live DB-backed proxy (Postgres, no mocks) and the PR's dashboard dev server. 33 of 35 checks passed; one real bug in the new UI component and one pre-existing gap that this feature inherits are described at the bottom

Config used

Proxy started with DATABASE_URL=postgresql://.../litellm PYTHONPATH=/path/to/validator litellm --config qa_config.yaml --port 4010, with LITELLM_LICENSE set in the env (nothing secret in the config itself)

general_settings:
  master_key: sk-1234
  custom_team_metadata_validate: qa_team_metadata_validator.validate_team_metadata
  team_metadata_validation_timeout: 3
  team_metadata_validation_error_message: "Cost center validation is unavailable right now; the team was not saved. Contact FinOps."
  team_metadata_schema:
    - key: cost_center
      label: "Cost Center"
    - key: app_name
      label: "Application Name"
    - key: chargeback_mode
      label: "Chargeback Mode"

The validator next to it accepts CC-1001 / CC-1002 and drives every branch of the contract: a missing cost center is rejected with its own message, CC-KABOOM raises, CC-SLOW hangs past the 3s timeout, CC-GARBAGE returns a malformed result, and CC-HTTPEXC raises an HTTPException(403)

import asyncio
from fastapi import HTTPException
from litellm.proxy.management_helpers.team_metadata_validation import (
    TeamMetadataValidationPayload,
    TeamMetadataValidationResult,
)

VALID_COST_CENTERS = {"CC-1001", "CC-1002"}

async def validate_team_metadata(payload: TeamMetadataValidationPayload) -> TeamMetadataValidationResult:
    cost_center = payload.metadata.get("cost_center")
    if cost_center == "CC-KABOOM":
        raise RuntimeError("simulated internal validation service outage")
    if cost_center == "CC-SLOW":
        await asyncio.sleep(30)
    if cost_center == "CC-GARBAGE":
        return {"not_a_valid": "result"}
    if cost_center == "CC-HTTPEXC":
        raise HTTPException(status_code=403, detail={"error": "validator said 403"})
    if cost_center is None:
        return TeamMetadataValidationResult(valid=False, error_message="Team metadata must include a cost_center. Contact the FinOps team.")
    if not isinstance(cost_center, str) or cost_center not in VALID_COST_CENTERS:
        return TeamMetadataValidationResult(valid=False, error_message=f"Cost center {cost_center!r} is not recognized. Contact the FinOps team.")
    return TeamMetadataValidationResult(valid=True)

def sync_validate_team_metadata(payload):
    return TeamMetadataValidationResult(valid=True)

Happy paths

$ curl -X POST localhost:4010/team/new -d '{"team_alias":"qa-valid-team","team_id":"qa-team-valid-1","metadata":{"cost_center":"CC-1001"}}'
{..."metadata":{"cost_center":"CC-1001"}...}                                                    HTTP 200

$ curl -X PATCH localhost:4010/team/qa-team-valid-1 -d '{"metadata":{"team_notes":"hello"}}'
{..."metadata":{"team_notes":"hello","cost_center":"CC-1001"}...}                               HTTP 200

$ curl -X POST localhost:4010/team/update -d '{"team_id":"qa-team-valid-1","metadata":{"cost_center":"CC-1002","team_notes":"hello"}}'
HTTP 200

$ curl -X POST localhost:4010/team/update -d '{"team_id":"qa-team-valid-1","tpm_limit":50}'     # no metadata key, validator skipped
HTTP 200

$ curl -X POST localhost:4010/team/new -d '{"team_alias":"qa-nested","team_id":"qa-team-nested-1","metadata":{"cost_center":"CC-1001","nested":{"a":[1,2,{"b":true}]},"flag":false,"num":1.5}}'
{..."metadata":{"num":1.5,"flag":false,"nested":{"a":[1,2,{"b":true}]},"cost_center":"CC-1001"}...}   HTTP 200

The PATCH payload the validator saw confirms the merged result and the requester identity, and that system-managed keys are stripped from both sides

[validator] operation=update team_id=qa-team-valid-1 metadata={'cost_center': 'CC-1001', 'team_notes': 'hello'} existing_metadata={'cost_center': 'CC-1001'} requester={'user_id': 'default_user_id', 'user_email': None, 'user_role': 'proxy_admin'}

Sad paths

$ curl -X POST localhost:4010/team/new -d '{"team_alias":"qa-bad-team","team_id":"qa-team-bad-1","metadata":{"cost_center":"CC-9999"}}'
{"error":{"message":"{'error': \"Cost center 'CC-9999' is not recognized. Contact the FinOps team.\"}",...,"code":"400"}}

$ curl -X POST localhost:4010/team/new -d '{"team_alias":"qa-no-meta-team","team_id":"qa-team-nometa-1"}'          # no metadata at all
{"error":{"message":"{'error': 'Team metadata must include a cost_center. Contact the FinOps team.'}",...,"code":"400"}}

$ curl -X POST localhost:4010/team/new -d '{"team_alias":"qa-empty-meta","team_id":"qa-team-empty-1","metadata":{}}'
HTTP 400

$ curl localhost:4010/team/info?team_id=qa-team-bad-1                                            # rejected create left no row
{"error":{"message":"{'message': 'Team not found, passed team id: qa-team-bad-1.'}",...,"code":"404"}}

$ curl -X PATCH localhost:4010/team/qa-team-valid-1 -d '{"metadata":{"cost_center":null}}'       # deleting the required key
HTTP 400

$ curl -X POST localhost:4010/team/update -d '{"team_id":"qa-team-valid-1","metadata":{"team_notes":"only-notes"}}'
HTTP 400

$ curl localhost:4010/team/info?team_id=qa-team-valid-1 | jq .team_info.metadata                 # blocked writes changed nothing
{"team_notes":"hello","cost_center":"CC-1002"}

Fail-closed and misconfiguration edge cases

$ curl -X POST localhost:4010/team/new -d '{...,"metadata":{"cost_center":"CC-KABOOM"}}'     # validator raises
{"error":{"message":"{'error': 'Cost center validation is unavailable right now; the team was not saved. Contact FinOps.'}",...,"code":"503"}}

$ curl -X POST localhost:4010/team/new -d '{...,"metadata":{"cost_center":"CC-SLOW"}}'       # hangs past team_metadata_validation_timeout: 3
HTTP 503, same generic message, returned after ~3s

$ curl -X POST localhost:4010/team/new -d '{...,"metadata":{"cost_center":"CC-GARBAGE"}}'    # malformed return value
HTTP 503

$ curl -X POST localhost:4010/team/new -d '{...,"metadata":{"cost_center":"CC-HTTPEXC"}}'    # validator raises HTTPException(403)
HTTP 503, generic message; the documented contract, the validator's own status is deliberately not surfaced

# proxy started with LITELLM_LICENSE unset
$ curl -X POST localhost:4011/team/new -d '{...,"metadata":{"cost_center":"CC-1001"}}'
{"error":{"message":"{'error': 'custom_team_metadata_validate is an Enterprise feature. You must be a LiteLLM Enterprise user...'}",...,"code":"400"}}

# custom_team_metadata_validate pointed at a non-async function
$ curl -X POST localhost:4012/team/new -d '{...,"metadata":{"cost_center":"CC-1001"}}'
{"error":{"message":"{'error': 'custom_team_metadata_validate must be an async function'}",...,"code":"500"}}

# no validator and no schema configured: behaviour is exactly as before
$ curl -X POST localhost:4013/team/new -d '{...,"metadata":{"cost_center":"CC-9999"}}'
HTTP 200
$ curl localhost:4013/team/metadata_schema -H 'Authorization: Bearer sk-1234'
{"fields":[]}

A rejected create that also carried model_aliases leaves no orphan row, so the fix for that review finding holds

$ curl -X POST localhost:4010/team/new -d '{"team_alias":"qa-alias-reject","team_id":"qa-team-alias-1","metadata":{"cost_center":"CC-9999"},"model_aliases":{"gpt":"fake-openai"}}'
HTTP 400
$ docker exec qa-pg psql -U postgres -d litellm -c 'select count(*) from "LiteLLM_ModelTable";'
 count
-------
     0

Schema endpoint and startup validation

$ curl localhost:4010/team/metadata_schema -H 'Authorization: Bearer sk-1234'
{"fields":[{"key":"cost_center","label":"Cost Center"},{"key":"app_name","label":"Application Name"},{"key":"chargeback_mode","label":"Chargeback Mode"}]}

$ curl -o /dev/null -w '%{http_code}\n' localhost:4010/team/metadata_schema                        # no key
401
$ curl -o /dev/null -w '%{http_code}\n' localhost:4010/team/metadata_schema -H 'Authorization: Bearer sk-wrong'
401

# non-admin (internal_user) key, the case the route-group fix was about
$ curl localhost:4010/team/metadata_schema -H "Authorization: Bearer $INTERNAL_USER_KEY"
{"fields":[{"key":"cost_center",...}]}                                                             HTTP 200

Malformed schemas fail proxy startup rather than serving a broken form

# unknown field name
exit code: 3
pydantic_core._pydantic_core.ValidationError: 1 validation error for tuple[TeamMetadataFieldSchema, ...]
  Extra inputs are not permitted [type=extra_forbidden, input_value=True, input_type=bool]

# duplicate keys
exit code: 3
ValueError: team_metadata_schema contains duplicate keys: cost_center

# empty key
exit code: 3
0.key
  String should have at least 1 character [type=string_too_short, input_value='', input_type=str]

Admin UI

Dashboard dev server on port 3000 (NEXT_PUBLIC_BASE_URL=http://localhost:4010 npm run dev) against the same proxy

The Metadata section renders as key-value rows directly under the RPM field, with no JSON textarea in Additional Settings, and is prepopulated from GET /team/metadata_schema

The rest of the UI matrix

• CC-9999 on create: blocked with Error creating the team: Cost center 'CC-9999' is not recognized. Contact the FinOps team., no ApiError: prefix and no {'error': ...} wrapper, and no row in /team/list
• cost_center row removed: Error creating the team: Team metadata must include a cost_center. Contact the FinOps team.
• CC-KABOOM: Error creating the team: Cost center validation is unavailable right now; the team was not saved. Contact FinOps.
• a second cost_center row: inline Duplicate key, the request never fires
• typed values round-trip: limits entered as {"a":1} is stored as a JSON object and redisplayed as {"a":1} in the edit form
• edit form prefills stored keys and leaks no UI-managed keys into the pair editor; saving CC-9999 is blocked with Failed to update team settings: ... and the form stays open; CC-1002 saves and /team/info shows the new value with the other keys untouched

Bug: blank metadata values are persisted as empty strings

Creating a team with only cost_center filled in, leaving the schema-seeded app_name and chargeback_mode rows untouched, saves them as empty strings

$ curl -sS 'http://localhost:4010/team/info?team_id=0e75256e-...' -H 'Authorization: Bearer sk-1234' | jq .team_info.metadata
{"limits": {"a": 1}, "app_name": "", "cost_center": "CC-1001", "chargeback_mode": ""}

The same happens on edit: clearing a stored value writes "limits": "" instead of removing the key. metadataPairsToObject in MetadataKeyValueFields.tsx keeps every pair that has a non-empty key, so dropping pairs whose value is empty or whitespace-only would fix both. This matters beyond tidiness because the validator now receives "" for schema keys the admin never filled in, so a validator written as if metadata.get("cost_center") is None: reject passes on an empty string. The PR description claims blank fields are omitted rather than saved as empty strings, so this looks like a regression against intent rather than a design choice

Pre-existing gap the feature inherits: metadata-backed top-level fields bypass the validator

An update that carries no metadata key but does carry a metadata-backed field such as tags skips validation and then overwrites the stored metadata wholesale, dropping the validated cost center

$ curl -X POST localhost:4010/team/update -d '{"team_id":"qa-team-valid-1","tags":["sneaky"]}'
HTTP 200
$ curl localhost:4010/team/info?team_id=qa-team-valid-1 | jq .team_info.metadata
{"tags":["sneaky"]}

The wholesale overwrite is pre-existing; I reproduced the same result on litellm_internal_staging with no validator configured, so it is not caused by this PR. It does mean the enforcement promise has a hole: a team admin can clear a required metadata key with a tags-only update. This is the same thing the veria-ai comment flagged, and it is worth either fixing here (validate the final materialized metadata rather than only updated_kv["metadata"]) or writing down as a known limitation. On create the same fields are merged in after validation, though there the merge is additive so the required key survives

[yuneng-berri]

@greptile A validator that raises HTTPException(403) does get converted to the generic 503 - this is intentional

review again

[yuneng-berri]

@veria-ai review