> This page is for 平台, version V4 实验版. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - 旧版: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # 管理用户权限 本指南介绍如何使用 Frame.io V4 API 管理用户权限。 其中包括各种权限在帐户、工作区和项目级别的工作原理，以及在每个级别使用的端点。 --- ## 权限级别 Frame.io 中的权限在帐户、工作区和项目级别进行管理。 每个级别都使用自己的角色集： ``` Account │ ├── (admin) - full access to all Workspaces, Projects, and Restricted Projects │ └── (member) │ ├── Workspace - (full_access | editor | edit_only | commenter | viewer) │ │ │ └── Project - (full_access | editor | edit_only | commenter | viewer) │ └── Restricted Project - (members require direct invite) ``` 每个用户都有一个帐户角色。 通过 API，您可以将用户的角色设置为 `admin` 或 `member`。 帐户管理员具有对所有工作区和项目的完全访问权限。 帐户成员可以有选择地添加到他们需要的工作区和项目中。 在您将帐户成员添加到工作区时，您分配的权限级别（`full_access`、`editor`、`edit_only`、`commenter` 或 `viewer`）适用于其中的所有现有和未来项目。 例如，如果您将帐户成员添加为 `viewer`，他们在访问该工作区中的任何项目时都将具有 `viewer` 权限。 同一位帐户成员可以作为 `editor` 添加到该工作区内的特定项目。 因此，每当他们访问该项目时，他们均将拥有 `editor` 权限。 他们的 `viewer` 权限继续适用于该工作区中的所有其他项目。 由于项目分配与工作区分配互相独立，如果您从工作区中移除该帐户成员，他们将保留对该单个项目的 `editor` 权限。 受限项目除外。 帐户成员始终需要直接邀请。 有关此内容的更多信息，请参阅下文的“项目级别权限”部分。 ## 帐户级别权限 您的帐户中的每个用户都有一个角色： | 角色 | 权限 | 可通过 API 配置 | 端点 | | -------- | -------------------------- | ---------- | -------------------------------------------- | | 所有者 | 对所有工作区和项目的完全访问权限。 每个帐户一个 | 否 | — | | `admin` | 对所有工作区和项目的完全访问权限 | 是 | `PATCH /accounts/:account_id/users/:user_id` | | `member` | 在工作区和/或项目级别设置的权限 | 是 | `PATCH /accounts/:account_id/users/:user_id` | | 审阅者 | 仅可通过共享链接访问。 将用户添加到安全共享项时创建 | 没有 | — | --- 帐户管理员拥有所有位置的完全访问权限。 要限制管理员对特定资源的访问权限，请先将其帐户角色更改为成员，然后将其添加到所需的工作区或项目。 例如： #### 列出帐户用户角色以查找用户 ID 并确认其当前角色： ```curl curl https://api.frame.io/v4/accounts/:account_id/users \ -H "Authorization: Bearer " ``` #### 将帐户角色更新为成员： ```curl curl -X PATCH https://api.frame.io/v4/accounts/:account_id/users/:user_id \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": { "role": "member" } }' ``` #### 将其添加到项目： ```curl curl -X PATCH https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users/:user_id \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": { "role": "edit_only" } }' ``` ### 帐户权限端点 #### 列出帐户用户角色 #### 列出帐户用户角色 \ 列出给定帐户中的用户，包括用户详细信息（ID、姓名、电子邮件地址）及其帐户角色。 \ `GET` `https://api.frame.io/v4/accounts/:account_id/users` \ [文档](/platform/api-reference/account-permissions/index) #### 更新用户角色 #### 更新用户角色 \ 更新帐户的用户角色。 此端点目前为实验性端点。 \ \ `PATCH` `https://api.frame.io/v4/accounts/:account_id/users/:user_id` \ [文档](/platform/v4-experimental/api-reference/account-permissions/developer-api-web-experimental-account-user-roles-controller-update) --- ## 工作区级别权限 在将帐户成员添加到工作区后，他们将拥有该工作区内所有项目的相应权限级别。 工作区仅限受邀用户加入，因此帐户成员只能看到他们被添加到的工作区。 \ | 角色 | 权限 | | ------------- | --------------------------- | | `full_access` | 上传、管理、共享、评论、查看、下载、管理设置和邀请用户 | | `editor` | 上传、管理、共享、评论、查看、下载 | | `edit_only` | 上传、管理、评论、查看。 无法共享或下载 | | `commenter` | 查看和评论 | | `viewer` | 仅查看 | \ ### 工作区权限端点 #### 列出工作区用户角色 #### 列出用户 \ 列出有权访问给定工作区的用户，包括用户详细信息（ID、姓名、电子邮件地址）及其角色。 \ `GET` `https://api.frame.io/v4/accounts/:account_id/workspaces/:workspace_id/users` \ [文档](/platform/api-reference/workspace-permissions/index) #### 更新用户角色 #### 更新用户角色 \ 修改用户在给定工作区中的角色。 这将更新用户的角色（如果他们已经添加到工作区中），或者使用给定的角色添加他们。 \ `PATCH` `https://api.frame.io/v4/accounts/:account_id/workspaces/:workspace_id/users/:user_id` \ [文档](/platform/api-reference/workspace-permissions/workspace-user-roles-update) #### 移除一名用户 #### 移除用户 \ 从给定工作区中移除用户 \ `DEL` `https://api.frame.io/v4/accounts/:account_id/workspaces/:workspace_id/users/:user_id` \ [文档](/platform/api-reference/workspace-permissions/workspace-user-roles-delete) --- ## 项目级别权限 项目使用与工作区相同的权限级别。 当用户只需要访问一个特定项目，或者需要与工作区分配不同的权限级别时，可以直接将用户添加到该项目。 用户无需拥有工作区访问权限即可被添加到项目中。 \ | 角色 | 权限 | | ----------------- | --------------------------- | | `full_access` | 上传、管理、共享、评论、查看、下载、管理设置和邀请用户 | | `editor` | 上传、管理、共享、评论、查看、下载 | | `edit_only` | 上传、管理、评论、查看。 无法共享或下载 | | `commenter` | 查看和评论 | | `viewer` | 仅查看 | | **示例：将用户添加到项目** | | ```curl curl -X PATCH https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users/:user_id \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": { "role": "full_access" } }' ``` --- ### 受限项目 受限项目需要直接邀请。 工作区访问权限不会沿用， 因此用户只有在被直接添加到受限项目时才能访问该项目。 要向成员授予访问权限，请将其添加到项目中并设置适当的权限级别。 > **Note** > > 帐户管理员和所有者是例外，他们可访问所有 > > 受限项目。 ### 项目权限端点 #### 列出项目用户角色 #### 列出项目用户角色 \ 列出有权访问给定项目的用户，包括用户详细信息（ID、姓名、电子邮件地址）及其角色。 \ `GET` `https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users` \ [文档](/platform/api-reference/project-permissions/index) #### 更新用户角色 #### 更新用户角色 \ 修改用户在给定项目中的角色。 这将更新用户的角色（如果他们已经添加到项目中），或者使用给定的角色添加他们。 \ `PATCH` `https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users/:user_id ` \ [文档](/platform/api-reference/project-permissions/project-user-roles-update) #### 移除一名用户 #### 移除一名用户 \ 从给定项目中移除用户 \ `DEL` `https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users/:user_id` \ [文档](/platform/api-reference/project-permissions/delete) --- ## 资源 您可能会发现以下资源很有帮助： * Frame.io [开发者论坛](https://forum.frame.io/)是开发者提出问题、共享反馈和讨论其构建内容的地方 * 关于用户角色和权限的[帮助中心文章](https://help.frame.io/zh-CN/articles/9875389-user-roles-and-permissions) * OWASP [授权备忘单](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html#prefer-attribute-and-relationship-based-access-control-over-rbac)，提供有关基于关系和属性的访问控制的更多信息