Access Control Reference

Capgo uses 基于角色的访问控制 (RBAC) 管理每个团队成员可以做什么。 角色按 范围 从整个组织到单个捆绑包的范围

查看管理成员的仪表板视觉教程，请参见 组织.

---

角色范围

范围

适用范围	例如：	使用场景
组织	整个组织及其所有应用	您的合伙人获得超级管理员;您的会计师获得账单管理员
应用	一个应用及其通道	一个只工作在一个应用上的承包商获得应用开发者
通道	一个应用中的一个通道	QA工程师只管理 staging 通道
捆绑包	一个捆绑包版本	一个审阅者需要对一个特定的发布有读取权限

一个成员可以在 一个范围目标上持有 例如，一个组织角色，一个 App A 角色，和一个 App B 角色

---

组织角色

这些角色在邀请成员时分配。它们授予对整个组织的访问权限

角色	内部名称	描述
超级管理员	org_super_admin	拥有者等同。包括删除组织、管理账单和转移应用的完全控制。自动授予给组织创建者
管理	org_admin	全局管理 — 管理成员、应用、频道。无法删除组织、更新账单、转移应用或提升用户为超级管理员。
账单管理员	org_billing_admin	仅限账单访问：查看和更新账单信息、发票和账单审计日志。无应用或成员访问权限。
成员	org_member	对组织和所有应用的只读访问。

组织权限矩阵

权限	描述	超级管理员	管理员	账单管理者	成员
org.read	查看组织	✅	✅	✅	✅
org.update_settings	编辑组织名称、Logo、管理邮箱	✅	✅	❌	❌
org.delete	永久删除组织	✅	❌	❌	❌
org.read_members	查看成员列表	✅	✅	❌	✅
org.invite_user	邀请新成员	✅	✅	❌	❌
org.update_user_roles	修改成员角色（管理员无法提升为超级管理员 — 角色层级限制）	✅	✅	❌	❌
org.read_billing	查看账单信息和当前计划	✅	✅	✅	❌
org.update_billing	更新支付方式和计划	✅	❌	✅	❌
org.read_invoices	查看发票	✅	✅	✅	❌
org.read_audit	查看组织活动日志	✅	✅	❌	❌
org.read_billing_audit	查看账单相关的审计日志	✅	✅	✅	❌

注意

组织角色会继承下属在层级中的应用、频道和包角色权限。 A 超级管理员 可以做所有 应用管理员 或 频道管理员 可以做的所有事情，跨所有应用和频道。

---

应用角色

仅限于一个应用。使用这些时，团队成员应该只在一个应用中工作，而不是整个组织。

角色	内部名称	描述
应用管理员	app_admin	一个应用的完全控制 — 通道、设备、应用用户角色。无法删除或转移应用（这些是组织级别的操作）。
应用开发者	app_developer	上传捆绑包、管理设备、触发本机构建、更新通道设置。无删除、无应用设置更改、无通道创建。
应用上传者	app_uploader	读取访问 + 上传新捆绑包版本。
应用读者	app_reader	只读 — 统计、捆绑包、通道、日志、设备。

应用权限矩阵

权限	描述	应用管理员	应用开发者	应用上传者	应用读者
app.read	查看应用详细信息、统计和元数据	✅	✅	✅	✅
app.update_settings	编辑应用设置	✅	❌	❌	❌
app.read_bundles	查看已上传的包列表	✅	✅	✅	✅
app.upload_bundle	上传新包版本	✅	✅	✅	❌
app.create_channel	创建新频道	✅	❌	❌	❌
app.read_channels	查看频道	✅	✅	✅	✅
app.read_logs	查看更新分发日志	✅	✅	✅	✅
app.manage_devices	Assign, override, or unlink 设备	✅	✅	❌	❌
app.read_devices	查看设备列表	✅	✅	✅	✅
app.build_native	触发本地云构建	✅	✅	❌	❌
app.read_audit	查看应用级活动日志	✅	✅	✅	✅
app.update_user_roles	管理应用级角色分配	✅	❌	❌	❌
bundle.delete	删除捆绑包	✅	❌	❌	❌

注意

app.delete 和 app.transfer targetLanguage":"Simplified Chinese" protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"] texts":["are","org-level operations","— 只能","can perform them, regardless of app-level roles.","Channel roles","Section titled “Channel roles”","Scoped to a single channel. Useful for giving targeted access to a specific release channel.","Note","Note","Channel roles are currently available","via __CAPGO_KEEP_0__ 和 __CAPGO_KEEP_1__ 只能","— 在控制台中没有 UI 来分配它们。 在控制台中，使用"]]} org_super_admin texts[0] = are

---

texts[1] = org-level operations

texts[3] = can perform them, regardless of app-level roles.

texts[5] = Section titled “Channel roles”

texts[6] = Scoped to a single channel. Useful for giving targeted access to a specific release channel. via API and CLI only texts[8] = Note 频道权限覆盖 而不是每个用户都细化频道访问。

角色	内部名称	描述
频道管理员	channel_admin	对一个频道有完全控制权：设置、推广/回滚包、管理强制设备。
频道浏览器	channel_reader	只读 — 当前包、历史记录、强制设备、审计日志。

频道权限矩阵

权限	描述	频道管理员	频道浏览者
channel.read	查看频道及其当前包	✅	✅
channel.update_settings	编辑频道设置（平台开关，更新策略…）	✅	❌
channel.delete	删除频道	✅	❌
channel.read_history	查看包分配历史	✅	✅
channel.promote_bundle	在频道上设置活动包	✅	❌
channel.rollback_bundle	回滚到之前的包	✅	❌
channel.manage_forced_devices	强制特定设备使用此频道	✅	❌
channel.read_forced_devices	查看强制设备列表	✅	✅
channel.read_audit	查看频道活动日志	✅	✅

---

Bundle roles

Scoped to a single bundle version. Rarely needed — most teams use app-level roles instead.

Note

Bundle roles are currently available via API and CLI only — there is no UI to assign them in the dashboard.

Role	Internal name	Description
Bundle Admin	bundle_admin	读取、更新元数据并删除特定包。
包查看器	bundle_reader	对特定包有只读访问权限。

---

渠道权限覆盖（控制台）

在控制台中，渠道访问由用户的应用角色确定。为了更细致的控制，您可以 覆盖特定渠道权限 在每个用户或组上覆盖而不改变他们的应用角色。

覆盖是从应用的 访问 选项卡中配置的，通过点击下面用户的渠道权限按钮（盾牌图标）。请参阅 组织—覆盖渠道权限 for a visual walkthrough.

可覆盖的权限

权限	描述	默认行为
读取	查看频道及其当前捆绑包	从应用角色继承
历史	查看捆绑包分配历史	从应用角色继承
关联包	设置或更改渠道上的活动包	继承自应用角色

每个权限可以设置为：

• 默认 — 从应用角色继承（默认）
• 允许 — 明确授予，忽略应用角色
• 拒绝 — 明确阻止，忽略应用角色

这让您可以，例如，给 App Reader 权限，让他们在渠道上关联包裹，而不必将他们提升为 App Developer。 staging __CAPGO_KEEP_0__

---

角色层级

角色形成层级结构。父角色 继承所有权限 的子角色。这意味着一个 org_admin 可以做任何一个 app_admin 可以做的任何事情， channel_admin 可以做的任何事情，

Super Admin (org_super_admin)
  └── Admin (org_admin)
        └── App Admin (app_admin)
              ├── App Developer (app_developer)
              │     └── App Uploader (app_uploader)
              │           └── App Reader (app_reader)
              ├── Bundle Admin (bundle_admin)
              │     └── Bundle Viewer (bundle_reader)
              └── Channel Admin (channel_admin)
                    └── Channel Viewer (channel_reader)

复制到剪贴板

• 在实际操作中： 一个 在组织级别可以对组织内的每个应用程序执行所有 应用程序管理员 可以在组织内的每个应用程序上执行所有
• 应用程序管理员 在特定应用程序上可以执行所有 频道管理员 频道 应用程序开发者
• 可以在应用程序中执行所有 应用程序上传者 can do everything an App Uploader 可以，更多功能。

层级结构只向下流动 — 一个 层级结构永远不会获得组织级别的权限，即使他们也持有应用级别的角色。 channel_admin 组

---

标题为“组”的部分

组 并将角色赋予组。组中的每个成员都会自动继承这些角色。 组的工作原理

标题为“组的工作原理”的部分

• 一个组属于 一个组织 —它不能跨越多个组织。
• 组可以在 任何范围：组织、应用、频道或捆绑包中持有角色绑定。例如，一个组可以被赋予 应用开发者 角色在应用A上，并且被赋予 频道管理员 角色在应用B的 staging 频道上。
• 当用户权限被评估时，所有他们的组成员身份都会透明地被解析。如果他们的任何组授予所需的权限，访问将被允许。
• 一个用户可以属于 多个组, 组内所有权限都是累加的。
• 基于组的权限仅适用于 用户主体 — API 键不继承组角色。

何时使用组

场景	没有组	有组
5 名 QA 工程师需要对 3 个应用程序拥有开发者访问权限	15个角色绑定	1个组 + 3个角色绑定
有人加入QA团队	手动添加3个角色绑定	将他们添加到组中
有人离开QA团队	手动删除3个角色绑定	从组中移除他们

通过API管理组

所有组端点都需要身份验证，并在 /private/groups.

组列表

curl -X GET "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>"

需要 org.read_members 权限。

创建组

curl -X POST "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Quality assurance engineers"
  }'

需要 org.update_user_roles 权限（超级管理员 或 管理员).

更新一个组

curl -X PUT "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Updated description"
  }'

删除一个组

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>"

删除一个组也会移除所有其角色绑定。成员不会从组织中删除。

组成员列表

curl -X GET "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>"

添加组成员

curl -X POST "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "<USER_UUID>" }'

用户必须已经是组织的成员。添加现有成员是无操作的。

从组中移除成员

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>/members/<USER_UUID>" \
  -H "authorization: <API_KEY>"

注意

要为组分配角色，请使用角色绑定 API principal_type: "group" 和 principal_id 设置为组 UUID。

---

通过 API 分配角色

成员列表

curl -X GET "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "<ORG_ID>" }'

响应：

[
  {
    "uid": "user-uuid",
    "email": "alice@example.com",
    "image_url": "https://...",
    "role": "org_admin",
    "is_tmp": false
  }
]

邀请成员

curl -X POST "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com",
    "invite_type": "org_admin"
  }'

接受的值 invite_type:

值	分配的角色
org_super_admin	超级管理员
org_admin	管理员
org_billing_admin	账单管理员
org_member	成员

移除成员

curl -X DELETE "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com"
  }'

---

通过CLI分配角色

列出组织

npx @capgo/cli organization list --apikey <API_KEY>

列出成员

npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>

注意

当前的CLI支持列出成员。要邀请成员或更改角色，使用上面的API API。

---

自定义角色

内置角色覆盖了大多数团队结构。自定义角色创建将在我们的路线图上 — 如果您的团队需要这个功能， 联系我们。您的用例将直接帮助我们优先考虑这个功能。

继续阅读Access Control Reference

If you are using __CAPGO_KEEP_0__ 访问控制参考 若要规划仪表板和 API 操作，连接它与 API 概览 若要了解 API 概览中的实现细节，请参阅 简介 若要了解简介中的实现细节，请参阅 API 密钥 若要了解 API 密钥中的实现细节，请参阅 设备 若要了解设备中的实现细节，请参阅 捆绑包 for the implementation detail in Bundles.