feat(ui): add role capability gating, migrate Tool Policies route

[yuneng-berri]

TLDR

Problem this solves:

• Internal users see Tool Policies but its data call always 401s
• The UI fires role-restricted calls without checking the caller's role

How it solves it:

• Adds a typed capability map as the single role-gating source
• A useCan hook gates the nav item, page, and query together
• The tools list call moves onto a TanStack queryOptions factory

Relevant issues

Linear ticket

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)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Backend behavior this PR aligns the UI with, captured at abe3289 (unchanged by this PR): the tools list route only serves admin roles

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4010/v1/tool/list -H "Authorization: Bearer sk-1234"
200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4010/v1/tool/list -H "Authorization: Bearer $INTERNAL_USER_KEY"
401

Before (abe3289): logged into the dashboard as an internal_user, the Tools group shows Tool Policies, the page renders its normal shell, and the network tab shows GET /v1/tool/list returning 401 on every visit

After (22b6062): same login shows no Tool Policies entry under Tools, a direct visit to /tool-policies renders an admin-only notice, and the network tab records zero /v1/tool/list requests. Admin login is unchanged: the entry is visible and the table loads

UI steps to reproduce the after-state for screenshots:

1. Start the proxy (python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload --use_v2_migration_resolver) and the dashboard dev server (npm run dev in ui/litellm-dashboard)
2. Create an internal user and set a password:

curl -s http://localhost:4000/user/new -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"user_email":"internal@example.test","user_role":"internal_user"}'

curl -s http://localhost:4000/user/update -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"user_id":"<user_id from above>","password":"some-password"}'

3. Log in at http://localhost:3000 as that user, expand Tools in the sidebar, and confirm only Search Tools and Vector Stores appear
4. Open http://localhost:3000/tool-policies directly and confirm the admin-only notice, with no /v1/tool/list request in the network tab
5. Log in as admin / master key and confirm Tool Policies is back in the sidebar and the table loads

Type

🐛 Bug Fix
🧹 Refactoring

Changes

src/utils/capabilities.ts introduces a capability-to-roles map with hasCapability and rolesWithCapability, and src/app/(dashboard)/hooks/useCan.ts exposes it as a hook. The point is a single source of truth: the sidebar entry, the page component, and the React Query enabled flag for a feature all read the same capability, so a role that cannot call an endpoint never sees the feature nor fires the request. This is the pattern for cleaning up the remaining role-restricted calls the dashboard currently fires for internal users; this PR migrates one route to keep the diff reviewable

Tool Policies is that route: leftnav.tsx gates the nav item via rolesWithCapability("viewToolPolicies"), ToolPoliciesView renders an admin-only notice for deep links, and ToolPoliciesPanel disables the query for non-admin roles. The tools list call also moves off a hand-rolled query key onto a queryOptions factory (toolPoliciesQueries.ts), which patchTool reuses for cache updates

Tests: capability grant/deny per role and copy semantics of rolesWithCapability, no fetch when the capability is missing, the deep-link notice replacing the overview, and sidebar visibility per role (hidden for internal users, shown for admins)

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

The PR introduces centralized UI capability gating and migrates Tool Policies data loading to a TanStack Query options factory.

• Gates the navigation item, deep-linked page, and tools-list query through viewToolPolicies.
• Prevents unauthorized roles from requesting the restricted tools-list endpoint.
• Reuses the query factory’s key for cache updates after policy changes.
• Adds coverage for capability checks, navigation visibility, deep-link behavior, and suppressed requests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
ui/litellm-dashboard/src/utils/capabilities.ts	Defines the typed capability map and defensive role-list accessor; its organization-admin denial is consistent with current backend route authorization.
ui/litellm-dashboard/src/app/(dashboard)/hooks/useCan.ts	Exposes capability checks using the authenticated dashboard role.
ui/litellm-dashboard/src/components/ToolPolicies/ToolPoliciesPanel.tsx	Gates tools-list fetching and migrates query/cache handling to the shared options factory.
ui/litellm-dashboard/src/components/ToolPolicies/toolPoliciesQueries.ts	Centralizes the Tool Policies list query key, fetch function, and refetch settings.
ui/litellm-dashboard/src/components/ToolPoliciesView.tsx	Replaces the Tool Policies interface with an access notice when the capability is absent.
ui/litellm-dashboard/src/components/leftnav.tsx	Restricts the Tool Policies navigation entry to roles granted the corresponding capability.

_{Reviews (3): Last reviewed commit: "test(ui): pin formatted Org Admin as den..." | Re-trigger Greptile}

[greptile-apps]

Formatted org-admin role is denied

When the JWT role is org_admin, useAuthorized formats it as Org Admin, but this capability list contains only the raw org_admin value. The exact-string check therefore hides Tool Policies, renders the admin-only notice on direct visits, and disables data loading for organization administrators.

Knowledge Base Used: Admin dashboard (ui/litellm-dashboard)

[yuneng-berri]

@greptile Backend parity: /v1/tool/list isn't in org_admin_allowed_routes, so org admins already got 401s; hiding the page matches existing admin-gated sidebar behavior.

Review again

[devin-ai-integration]

QA: PASS — no blocking issues

Tested the PR head (00f91453c9) on a dashboard dev server at :3000 against a live proxy on :4000, with the merge-base (487074f602) served from a git worktree on :3001 as the BEFORE control. Same proxy, same login, so the only variable is the frontend code.

The internal-user fix holds: the nav child disappears, the deep link renders the admin-only notice, and GET /v1/tool/list stops being fired entirely. Admin access, policy writes, and the tool detail drill-down are all unaffected by the queryOptions refactor.

Proxy config for the QA session was the repo's unmodified litellm/proxy/dev_config.yaml (master_key: sk-1234), started with

sudo service postgresql start
(cd litellm/proxy && uv run --no-sync prisma db push --accept-data-loss --skip-generate)
uv run --no-sync litellm --config litellm/proxy/dev_config.yaml --detailed_debug --port 4000

and the two dashboards with npm run dev in ui/litellm-dashboard (PR head, :3000) and npm run dev -- --port 3001 in the merge-base worktree. The tool rows come from real Anthropic calls through the proxy (anthropic-sonnet-4-6 with a three-function tools array), so get_weather, run_sql_query and send_email are genuinely auto-discovered rows, not fixtures.

Before / after for the same internal_user login

BEFORE (:3001): Tool Policies is listed under Tools and the page renders its shell with a 401 banner for Route=/v1/tool/list. Your role=internal_user. The proxy log went from 15 to 19 matching requests across one reload, every one a 401.

AFTER (:3000): the Tools group still renders, with only Search Tools and Vector Stores; the direct visit to /tool-policies shows Tool Policies is only available to admin users.

DevTools filtered to tool/list after a full reload of the deep link reads 0 / 75 requests, and grep -c '"GET /v1/tool/list' litellm.log stayed flat at 19 across the visit, then flat again across a reload and a Back/Forward pair.

Admin happy path and policy write-through

Table loads the 3 discovered tools with Total Tools Discovered at 3. Setting get_weather input policy to blocked moved Blocked Tools from 0 to 1 and Needs Review from 3 tools to 2, which is the check that matters for patchTool now writing through listOptions.queryKey. Output policy went to trusted without reverting. Both survived a hard reload, and the API agrees:

$ curl -s http://localhost:4000/v1/tool/list -H "Authorization: Bearer sk-1234"
[('send_email','untrusted','untrusted'), ('run_sql_query','untrusted','untrusted'), ('get_weather','blocked','trusted')]

The detail drill-down still opens and reflects both policies; Back returns to the table with values intact. get_weather was restored to untrusted/untrusted afterwards

Role matrix

Login	Role	Nav entry	Page	/v1/tool/list
admin (master key)	Admin	shown	table, 3 tools	200
admin2@example.test	proxy_admin	shown	table, 3 tools	200
adminviewer@example.test	proxy_admin_viewer	shown	table, 3 tools	200
internal@example.test	internal_user	hidden	notice	0 requests
internalviewer@example.test	internal_user_viewer	hidden	notice	0 requests

Every row matches what the API returns for that role, checked independently with a key per user, so the capability map is neither over- nor under-gating.

Also confirmed the gate flips both ways in one session without a stale cache: with admin2's fully loaded table on screen, logging out and back in as the internal user swapped straight to the notice with no leaked rows and no request.

Admin Viewer write attempt (not a gap)

The policy select is left enabled for the read-only role, so I tried a write. The backend refuses it and the row does not change:

Failed to update input policy: {"error":{"message":"user not allowed to access this route, role= proxy_admin_viewer. Trying to access: /v1/tool/policy","type":"auth_error","param":"None","code":"403"}}

Same result posting directly with the viewer's key (HTTP 403, registry unchanged). Worth disabling the control for read-only roles eventually, but that is pre-existing and not this PR

Tests, mutation check, lint

The four touched test files pass (53 tests). Mutation-checked rather than taken at face value: removing the nav roles entry, replacing the !canViewToolPolicies guard in ToolPoliciesView with false, and dropping canViewToolPolicies from the query's enabled each fail a test; making rolesWithCapability return the map's array instead of a copy fails the copy test. One gap, harmless: deleting the userRole != null guard in hasCapability kills no test, since includes(undefined) is already false.

npx tsc --noEmit reports errors only in tests/top_key_view.test.tsx, which this PR does not touch and which fails the same way on the merge-base. eslint on the six touched source files is clean apart from warnings, one of them new: local/no-large-inline-object-arg on the queryOptions({...}) call in toolPoliciesQueries.ts. The only red CI check is osv-scan, a dependency scan unrelated to this diff

Out of scope, for the follow-up in this series

/vector-stores is still listed for internal users and fires GET /credentials, giving two 401 toasts; GET /health/license also still 401s on every page. Same bug class the capability map exists to fix, on routes this PR did not migrate

One nit on the map itself: useAuthorized().userRole is formatUserRole(...), so the raw proxy_admin / proxy_admin_viewer / org_admin entries inside all_admin_roles can never match at runtime; the map effectively grants "Admin" and "Admin Viewer". Behavior is still correct today (an org_admin resolves to "Internal User" and the backend 401s them anyway, so that login was not exercised end to end), but those entries are dead weight and make the grant look broader than it is

Devin session: https://app.devin.ai/sessions/33a712ebd50443a5bd5b753f74d94ced

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yuneng-berri]

@greptile Verified live at 0c3020d: a membership-granted org admin key returns 401 on /v1/tool/list; added a test pinning formatted Org Admin as intentionally denied.

review again