基于角色的访问控制 (RBAC)

基于角色的访问控制 (RBAC) 基于组织、团队和内部用户角色。

Organizations (组织) 是包含团队的顶级实体。
Team (团队) - 团队是多个 Internal Users (内部用户) 的集合。
Internal Users (内部用户) - 可以创建密钥、进行 LLM API 调用、查看 LiteLLM 使用情况的用户。用户可以属于多个团队。
Virtual Keys (虚拟密钥) - 密钥用于 LiteLLM API 的身份验证。每个密钥可以选择性地关联一个 user_id、一个 team_id，或两者兼有。
- 仅用户密钥 (User-only key): 拥有 user_id 但没有 team_id。单独跟踪，当用户被删除时，密钥也会被删除。
- 团队密钥 (服务账户): 拥有 team_id 但没有 user_id。由团队共享，当用户被移除时不会被删除。了解有关服务账户密钥的更多信息。
- 用户+团队密钥: 同时拥有 user_id 和 team_id。属于团队环境下的特定用户。

何时使用每种类型的密钥

密钥类型	用例	消费跟踪	生命周期
仅用户 (User-only)	供个人开发者使用的个人 API 密钥	跟踪至用户	用户被删除时随之删除
团队 (服务账户)	生产应用、CI/CD 流水线、共享服务	仅跟踪至团队	团队成员离开后仍保留
用户 + 团队	在团队环境内工作的用户	同时跟踪至用户和团队	用户被删除时随之删除

示例场景

对本地测试的开发者使用 仅用户密钥
对不应因员工离职而中断的生产应用程序使用 团队服务账户密钥
当您希望在团队预算内实现个人责任归属时，使用 用户+团队密钥

用户角色

LiteLLM 有两种类型的角色

全局代理角色 (Global Proxy Roles) - 适用于所有组织和团队的平台级角色
组织/团队特定角色 (Organization/Team Specific Roles) - 作用域限于特定组织或团队的角色 (高级功能)

全局代理角色

角色名称	权限
`proxy_admin`	整个平台的管理员。对所有组织、团队和用户拥有完全控制权
`proxy_admin_viewer`	可以登录，查看平台内所有密钥和所有支出。不能创建/删除密钥或添加新用户
`internal_user`	可以登录，查看/创建（在团队特定权限允许时）/删除自己的密钥，查看自己的支出。不能添加新用户
`internal_user_viewer`	⚠️ 已弃用 - 请改用团队/组织特定角色。可以登录，查看自己的密钥和支出。不能创建/删除密钥，也不能添加新用户

组织/团队特定角色

角色名称	权限
`org_admin`	特定组织的管理员。可以在其组织内创建团队和用户 ✨ 高级功能
`team_admin`	特定团队的管理员。可以管理团队成员，更新成员权限，并为其团队创建密钥。 ✨ 高级功能

每个角色能做什么？

以下是每个角色实际能做的操作。可以将其理解为访问级别。

全局代理角色

这些角色适用于整个 LiteLLM 平台，无论组织或团队边界如何。

代理管理员 (Proxy Admin) - 完全访问权限

代理管理员控制一切。他们就像整个平台的所有者。

他们能做什么

创建并管理所有组织
创建并管理所有团队（跨所有组织）
创建并管理所有用户
查看整个平台的所有支出和使用情况
为任何人创建和删除密钥
更新团队预算、速率限制和模型
管理团队成员并分配角色

谁应该成为代理管理员： 只有运行 LiteLLM 实例的人员。

代理管理员查看者 (Proxy Admin Viewer) - 平台级只读访问权限

代理管理员查看者可以查看平台内的一切，但无法进行任何更改。

他们能做什么

查看所有组织、团队和用户
查看整个平台的所有支出和使用情况
查看所有 API 密钥
登录到管理仪表板

他们不能做什么

创建或删除密钥
添加或移除用户
修改预算、速率限制或设置
对平台进行任何更改

谁应该成为代理管理员查看者： 财务团队、审计员或需要平台级可见性但无需修改权限的利益相关者。

内部用户 (Internal User)

内部用户可以创建 API 密钥（在团队特定权限允许时）并进行调用。他们只能查看自己的内容。如果被分配了相应的角色，他们可以成为团队管理员或组织管理员。

他们能做什么

为自己创建 API 密钥
删除自己的 API 密钥
查看自己的支出和使用情况
使用其密钥进行 API 调用

谁应该成为内部用户： 任何需要 UI 访问权限进行特定团队/组织操作的人，或者您计划分配多个密钥的开发者。

内部用户查看者 (Internal User Viewer) - 只读访问权限

已弃用

此角色已被弃用，建议改用团队/组织特定角色。使用 org_admin 或 team_admin 角色，以便在组织和团队内对用户权限进行更细粒度的控制。

内部用户查看者可以查看自己的信息，但不能创建或删除密钥。

他们能做什么

查看自己的 API 密钥
查看自己的支出和使用情况
登录查看自己的仪表板

他们不能做什么

创建或删除 API 密钥
修改任何设置
创建团队或添加用户
查看他人的信息

谁应该成为内部用户查看者 (已弃用)： 请考虑改用特定于团队/组织的角色以实现更好的访问控制。

组织/团队特定角色

信息

组织/团队特定角色属于高级功能。您需要成为 LiteLLM 企业版用户才能使用它们。点击此处获取 7 天试用。

这些角色的作用域仅限于特定组织或团队。拥有这些角色的用户只能管理其分配的组织或团队内的资源。

组织管理员 (Org Admin) - 组织级别访问权限

组织管理员管理一个或多个组织。他们可以在其组织内创建团队，但无法触及其他组织。

他们能做什么

在其组织内创建团队
向其组织内的团队添加用户
查看其组织的支出
为其组织内的用户创建密钥

他们不能做什么

创建或管理其他组织
修改组织预算/速率限制
修改组织允许的模型（例如，将代理级模型添加到组织）

谁应该成为组织管理员： 需要管理多个团队的部门主管或经理。

团队管理员 (Team Admin) - 团队级别访问权限

✨ 这是一个高级功能

团队管理员管理特定的团队。他们就像团队领导，可以添加人员、更新设置，但仅限于他们的团队。

他们能做什么

从团队中添加或移除团队成员
更新团队成员在团队内的预算和速率限制
更改团队设置（预算、速率限制、模型）
为团队成员创建和删除密钥
将团队 BYOK 模型接入 LiteLLM（例如接入团队自调优的模型）
配置团队成员权限以控制普通团队成员的操作权限

他们不能做什么

创建新团队
修改团队的预算/速率限制
向其团队添加/移除全局代理模型

谁应该成为团队管理员： 需要管理团队 API 访问权限而无需麻烦 IT 部门的团队主管。

如何创建团队管理员

您需要成为 LiteLLM 企业版用户才能分配团队管理员。点击此处获取 7 天试用。

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
    -H 'Authorization: Bearer sk-1234' \
    -H 'Content-Type: application/json' \
    -d '{"team_id": "team-123", "member": {"role": "admin", "user_id": "user@company.com"}}'

团队成员权限

✨ 这是一个高级功能

团队成员权限允许您控制普通团队成员（role=user）在其团队中对 API 密钥的操作权限。默认情况下，团队成员只能查看密钥信息，但您可以授予他们创建、更新或删除密钥的额外权限。

工作原理

适用范围：角色为 user 的团队成员（不包括团队管理员或组织管理员）
作用域：权限仅适用于属于其团队的密钥
配置：使用 team_member_permissions 在团队级别设置
覆盖：无论这些设置如何，团队管理员和组织管理员始终拥有完全权限

可用权限

权限	方法	描述
`/key/info`	GET	查看团队内虚拟密钥的信息
`/key/health`	GET	检查团队内虚拟密钥的健康状态
`/key/list`	GET	列出属于该团队的所有虚拟密钥
`/key/generate`	POST	为团队创建新的虚拟密钥
`/key/service-account/generate`	POST	为团队创建服务账户密钥（不与特定用户绑定）
`/key/update`	POST	修改团队内现有的虚拟密钥
`/key/delete`	POST	删除属于该团队的虚拟密钥
`/key/regenerate`	POST	重新生成团队内的虚拟密钥
`/key/block`	POST	封禁团队内的虚拟密钥
`/key/unblock`	POST	解封团队内的虚拟密钥

默认权限

默认情况下，团队成员只能

/key/info - 查看密钥信息
/key/health - 检查密钥健康状态

常见权限场景

只读访问 (默认)

["/key/info", "/key/health"]

允许创建密钥，但不允许删除:

["/key/info", "/key/health", "/key/generate", "/key/update"]

完全密钥管理:

["/key/info", "/key/health", "/key/generate", "/key/update", "/key/delete", "/key/regenerate", "/key/block", "/key/unblock", "/key/list"]

如何配置团队成员权限

查看当前权限

curl --location 'http://0.0.0.0:4000/team/permissions_list?team_id=team-123' \
    --header 'Authorization: Bearer sk-1234'

预期响应

{
  "team_id": "team-123",
  "team_member_permissions": ["/key/info", "/key/health"],
  "all_available_permissions": ["/key/generate", "/key/update", "/key/delete", ...]
}

更新团队成员权限

curl --location 'http://0.0.0.0:4000/team/update' \
    --header 'Authorization: Bearer sk-1234' \
    --header 'Content-Type: application/json' \
    --data '{
        "team_id": "team-123",
        "team_member_permissions": ["/key/info", "/key/health", "/key/generate", "/key/update"]
    }'

这允许团队成员

查看密钥信息
创建新密钥
更新现有密钥
但不能删除密钥

谁可以配置这些权限？

代理管理员：可以为任何团队配置权限
组织管理员：可以为其组织内的团队配置权限
团队管理员：可以为自己的团队配置权限

快速对比

简要版本如下

全局代理角色

操作	代理管理员	代理管理员查看者	内部用户	内部用户查看者 ⚠️ (已弃用)
创建组织	✅	❌	❌	❌
创建团队	✅	❌	❌	❌
管理所有团队	✅	❌	❌	❌
创建/删除任何密钥	✅	❌	❌	❌
创建/删除自己的密钥	✅	❌	✅	❌
查看所有平台支出	✅	✅	❌	❌
查看自己的支出	✅	✅	✅	✅
查看所有密钥	✅	✅	❌	❌
查看自己的密钥	✅	✅	✅	✅
添加/移除用户	✅	❌	❌	❌

注意： internal_user_viewer 角色已弃用。请使用特定于团队/组织的角色以实现更细粒度的访问控制。

组织/团队特定角色

操作	组织管理员	团队管理员
创建团队（在其组织内）	✅	❌
管理其组织内的团队	✅	❌
管理其特定团队	✅	✅
添加/移除团队成员	✅ (在其组织内)	✅ (仅其团队)
更新团队预算	✅ (在其组织内)	✅ (仅其团队)
为团队成员创建密钥	✅ (在其组织内)	✅ (仅其团队)
查看组织支出	✅ (在其组织内)	❌
查看团队支出	✅ (在其组织内)	✅ (其团队)
创建组织	❌	❌
查看所有平台支出	❌	❌

组织入驻流程

✨ 这是一个高级功能

1. 创建新组织

任何角色为 proxy_admin 的用户都可以创建新组织

用法

/organization/new API 参考

curl --location 'http://0.0.0.0:4000/organization/new' \
    --header 'Authorization: Bearer sk-1234' \
    --header 'Content-Type: application/json' \
    --data '{
        "organization_alias": "marketing_department",
        "models": ["gpt-4"],
        "max_budget": 20
    }'

预期响应

{
  "organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23",
  "organization_alias": "marketing_department",
  "budget_id": "98754244-3a9c-4b31-b2e9-c63edc8fd7eb",
  "metadata": {},
  "models": [
    "gpt-4"
  ],
  "created_by": "109010464461339474872",
  "updated_by": "109010464461339474872",
  "created_at": "2024-10-08T18:30:24.637000Z",
  "updated_at": "2024-10-08T18:30:24.637000Z"
}

2. 向组织添加 `org_admin`

为 marketing_department 组织创建用户 (ishaan@berri.ai) 并将其设为 org_admin（来自步骤 1）

拥有以下角色的用户可以调用 /organization/member_add

proxy_admin
org_admin 仅限于其自己的组织内

curl -X POST 'http://0.0.0.0:4000/organization/member_add' \
    -H 'Authorization: Bearer sk-1234' \
    -H 'Content-Type: application/json' \
    -d '{"organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23", "member": {"role": "org_admin", "user_id": "ishaan@berri.ai"}}'

现在，已在 marketing_department 组织中创建了 user_id = ishaan@berri.ai 且角色 = org_admin 的用户

为 user_id = ishaan@berri.ai 创建虚拟密钥。该用户随后可以使用此虚拟密钥执行组织管理员操作

curl --location 'http://0.0.0.0:4000/key/generate' \
        --header 'Authorization: Bearer sk-1234' \
        --header 'Content-Type: application/json' \
        --data '{
            "user_id": "ishaan@berri.ai"
    }'

预期响应

{
  "models": [],
  "user_id": "ishaan@berri.ai",
  "key": "sk-7shH8TGMAofR4zQpAAo6kQ",
  "key_name": "sk-...o6kQ",
}

3. `组织管理员` - 创建团队

组织管理员将使用在步骤 2 中创建的虚拟密钥，在 marketing_department 组织内创建一个 Team

curl --location 'http://0.0.0.0:4000/team/new' \
    --header 'Authorization: Bearer sk-7shH8TGMAofR4zQpAAo6kQ' \
    --header 'Content-Type: application/json' \
    --data '{
        "team_alias": "engineering_team",
        "organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23"
    }'

这将在 marketing_department 组织内创建 engineering_team

预期响应

{
  "team_alias": "engineering_team",
  "team_id": "01044ee8-441b-45f4-be7d-c70e002722d8",
  "organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23",
}

4. `组织管理员` - 添加团队管理员

✨ 这是一个高级功能

组织管理员现在可以添加一名团队管理员，该团队管理员将管理 engineering_team。

我们分配 role=admin 将其设为该特定团队的团队管理员
team_id 来自步骤 3

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
    -H 'Authorization: Bearer sk-7shH8TGMAofR4zQpAAo6kQ' \
    -H 'Content-Type: application/json' \
    -d '{"team_id": "01044ee8-441b-45f4-be7d-c70e002722d8", "member": {"role": "admin", "user_id": "john@company.com"}}'

现在 john@company.com 是团队管理员。他们可以管理 engineering_team - 添加成员、更新预算、创建密钥 - 但不能触及其他团队。

为团队管理员创建虚拟密钥

curl --location 'http://0.0.0.0:4000/key/generate' \
    --header 'Authorization: Bearer sk-7shH8TGMAofR4zQpAAo6kQ' \
    --header 'Content-Type: application/json' \
    --data '{"user_id": "john@company.com"}'

预期响应

{
  "models": [],
  "user_id": "john@company.com",
  "key": "sk-TeamAdminKey123",
  "key_name": "sk-...Key123"
}

5. `团队管理员` - 添加团队成员

现在团队管理员可以使用他们的密钥来添加团队成员，无需请求组织管理员。

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
    -H 'Authorization: Bearer sk-TeamAdminKey123' \
    -H 'Content-Type: application/json' \
    -d '{"team_id": "01044ee8-441b-45f4-be7d-c70e002722d8", "member": {"role": "user", "user_id": "krrish@berri.ai"}}'

团队管理员还可以为其团队成员创建密钥

curl --location 'http://0.0.0.0:4000/key/generate' \
    --header 'Authorization: Bearer sk-TeamAdminKey123' \
    --header 'Content-Type: application/json' \
    --data '{
        "user_id": "krrish@berri.ai",
        "team_id": "01044ee8-441b-45f4-be7d-c70e002722d8"
    }'

6. `团队管理员` - 更新团队设置

团队管理员可以更新团队预算和速率限制

curl --location 'http://0.0.0.0:4000/team/update' \
    --header 'Authorization: Bearer sk-TeamAdminKey123' \
    --header 'Content-Type: application/json' \
    --data '{
        "team_id": "01044ee8-441b-45f4-be7d-c70e002722d8",
        "max_budget": 100,
        "rpm_limit": 1000
    }'

何时使用每种类型的密钥​

用户角色​

全局代理角色​

组织/团队特定角色​

每个角色能做什么？​

全局代理角色​

代理管理员 (Proxy Admin) - 完全访问权限​

代理管理员查看者 (Proxy Admin Viewer) - 平台级只读访问权限​

内部用户 (Internal User)​

内部用户查看者 (Internal User Viewer) - 只读访问权限​

组织/团队特定角色​

组织管理员 (Org Admin) - 组织级别访问权限​

团队管理员 (Team Admin) - 团队级别访问权限​

团队成员权限​

工作原理​

可用权限​

默认权限​

常见权限场景​

如何配置团队成员权限​

查看当前权限​

更新团队成员权限​

谁可以配置这些权限？​

快速对比​

全局代理角色​

组织/团队特定角色​

组织入驻流程​

1. 创建新组织​

2. 向组织添加 org_admin​

3. 组织管理员 - 创建团队​

4. 组织管理员 - 添加团队管理员​

5. 团队管理员 - 添加团队成员​

6. 团队管理员 - 更新团队设置​

何时使用每种类型的密钥

用户角色

全局代理角色

组织/团队特定角色

每个角色能做什么？

全局代理角色

代理管理员 (Proxy Admin) - 完全访问权限

代理管理员查看者 (Proxy Admin Viewer) - 平台级只读访问权限

内部用户 (Internal User)

内部用户查看者 (Internal User Viewer) - 只读访问权限

组织/团队特定角色

组织管理员 (Org Admin) - 组织级别访问权限

团队管理员 (Team Admin) - 团队级别访问权限

团队成员权限

工作原理

可用权限

默认权限

常见权限场景

如何配置团队成员权限

查看当前权限

更新团队成员权限

谁可以配置这些权限？

快速对比

全局代理角色

组织/团队特定角色

组织入驻流程

1. 创建新组织

2. 向组织添加 `org_admin`

3. `组织管理员` - 创建团队

4. `组织管理员` - 添加团队管理员

5. `团队管理员` - 添加团队成员

6. `团队管理员` - 更新团队设置