From 0ce263179497a8a8b01526e5968c8375a0922a4c Mon Sep 17 00:00:00 2001 From: ryan-crabbe-berri Date: Fri, 5 Jun 2026 11:44:08 -0700 Subject: [PATCH] docs(proxy): document auth_v2 v1 tenancy model (global roles + optional domain scoping) --- litellm/proxy/auth/v2/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/litellm/proxy/auth/v2/README.md b/litellm/proxy/auth/v2/README.md index 62f67249f4f..cfcfea05a60 100644 --- a/litellm/proxy/auth/v2/README.md +++ b/litellm/proxy/auth/v2/README.md @@ -94,6 +94,22 @@ curl -sX POST localhost:4000/auth/v2/policy/assignment/add \ curl -s localhost:4000/auth/v2/policy/list -H "Authorization: Bearer $MASTER_KEY" ``` +## Tenancy model + +v1 uses **global roles with optional domain scoping**, not forced per-tenant +isolation. A role assignment is global by default (a `g` row), so the role +applies everywhere. To scope a role to one tenant, assign it within a `domain` +(a `g3` row, e.g. `team:eng` or `org:acme`); the role then grants its permissions +only in that domain. This is how a per-org admin is expressed: assign the admin +role scoped to that org's domain, and it cannot touch other orgs. + +Deliberately deferred: **automatic** isolation where every resource is implicitly +domain-qualified and a request is confined to the caller's own org/team without +any explicit scoping. That is a larger model (every resource object must carry +its owning domain, and the matcher must enforce it on every check) and is left to +a later version. Until then, isolation is opt-in per role assignment via the +domain field, which already covers the common "admin of just this org/team" case. + ## Live verification runbook Prereq: generate a migration for `LiteLLM_CasbinRule`, run `make format`,