用户管理 API

完整的 API 参考，用于管理 Blue 项目和公司的用户、邀请、角色和权限

概述

用户管理 API 提供了全面的工具，用于管理团队成员、控制访问权限以及在 Blue 项目和公司中组织您的劳动力。无论您是在添加新团队成员、管理现有用户，还是定义自定义权限结构，这些 API 都能处理用户生命周期管理的各个方面。

在 Blue 中的用户管理分为两个层级：

项目级：在特定项目中管理用户，并具有项目特定的权限
公司级：在整个组织中管理用户，并具有公司范围的访问权限

可用操作

核心用户管理

操作	描述	链接
Invite User	向具有特定访问级别的新用户发送邀请	View Details →
List Users	查询和过滤项目或公司的用户	View Details →
Remove User	从项目或公司中移除用户	View Details →

角色和权限管理

操作	描述	链接
Custom Roles	创建和管理具有细粒度权限的自定义角色	View Details →

访问级别

Blue 提供了一个分层权限系统，具有预定义的访问级别：

标准访问级别

级别	描述	能力
OWNER	对项目/公司的完全控制	All permissions, can transfer ownership
ADMIN	管理员访问	User management, settings, billing
MEMBER	标准团队成员	Full project functionality, limited admin access
CLIENT	外部客户访问	Limited project visibility, focused on deliverables
COMMENT_ONLY	仅评论访问	可以查看和评论，不能编辑
VIEW_ONLY	只读访问	Can view content only

权限层级

用户只能邀请或管理其级别或以下的用户：

所有者可以管理所有访问级别
管理员可以管理管理员、成员、客户、仅评论、仅查看
成员可以管理成员、客户、仅评论、仅查看
客户只能管理其他客户

关键概念

用户邀请

基于电子邮件：通过电子邮件地址邀请用户
角色分配：在邀请时设置访问级别和可选的自定义角色
多项目：单个邀请可以授予对多个项目的访问
过期：邀请在 7 天后过期
自动通知：Blue 自动发送电子邮件邀请

项目与公司访问

项目邀请：仅授予对特定项目的访问
公司邀请：授予公司级别的访问，选项包括特定项目
公司所有者：自动获得对所有公司项目的管理员访问权限
范围限制：不能将项目和公司邀请参数结合使用

自定义角色

细粒度权限：定义超出标准访问级别的特定能力
项目特定：自定义角色仅限于单个项目
字段级控制：控制对特定自定义字段的访问
操作限制：限制特定操作（创建、编辑、删除等）

常见模式

邀请新团队成员

mutation InviteTeamMember {
  inviteUser(input: {
    email: "john.doe@company.com"
    projectId: "web-redesign"
    accessLevel: MEMBER
  })
}

创建公司范围的邀请

mutation InviteToCompany {
  inviteUser(input: {
    email: "manager@company.com"
    companyId: "company_123"
    projectIds: ["project_1", "project_2", "project_3"]
    accessLevel: ADMIN
  })
}

列出项目用户

query ProjectUsers {
  projectUsers(projectId: "web-redesign") {
    id
    user {
      name
      email
      avatar
    }
    accessLevel
    role {
      name
      permissions
    }
    invitedAt
    joinedAt
  }
}

移除用户

mutation RemoveProjectUser {
  removeUser(input: {
    userId: "user_456"
    projectId: "web-redesign"
  })
}

创建自定义角色

mutation CreateCustomRole {
  createProjectUserRole(input: {
    projectId: "web-redesign"
    name: "Content Reviewer"
    permissions: {
      canCreateRecords: false
      canEditOwnRecords: true
      canEditAllRecords: false
      canDeleteRecords: false
      canManageUsers: false
      canViewReports: true
    }
  }) {
    id
    name
    permissions
  }
}

权限管理

标准权限矩阵

操作	所有者	管理员	成员	客户	仅评论	仅查看
Invite Users	✅ 所有级别	✅ 管理员及以下	✅ 成员及以下	✅ 仅客户	❌ 不可	❌ 不可
Remove Users	✅ 所有用户	✅ 管理员及以下	✅ 成员及以下	✅ 仅客户	❌ 不可	❌ 不可
Modify Project Settings	✅ 是	✅ 是	❌ 不可	❌ 不可	❌ 不可	❌ 不可
Create Records	✅ 是	✅ 是	✅ 是	✅ 有限	❌ 不可	❌ 不可
Edit All Records	✅ 是	✅ 是	✅ 是	❌ 不可	❌ 不可	❌ 不可
Delete Records	✅ 是	✅ 是	✅ 是	❌ 不可	❌ 不可	❌ 不可
View Reports	✅ 是	✅ 是	✅ 是	✅ 有限	❌ 不可	❌ 不可

自定义角色能力

字段级权限：控制对特定自定义字段的访问
操作特定规则：允许/拒绝特定操作（创建、编辑、删除）
查看限制：限制用户可以看到的记录
功能切换：为每个角色启用/禁用特定功能

最佳实践

用户入职

从标准角色开始 - 对大多数用户使用预定义的访问级别
逐步权限 - 从有限的访问开始，按需扩展
清晰沟通 - 在发送邀请时包含上下文
定期审查 - 定期审核用户访问权限

安全考虑

最小权限原则 - 授予最低必要权限
定期访问审核 - 每季度审核用户权限
离职流程 - 用户离开时立即撤销访问权限
自定义角色文档 - 记录自定义角色的目的和限制

团队组织

一致的命名 - 使用清晰、描述性的角色名称
角色整合 - 避免创建过多相似的自定义角色
公司结构 - 将权限与组织层级对齐
项目继承 - 考虑公司角色如何影响项目访问

错误处理

管理用户时常见的错误：

错误代码	描述	解决方案
`USER_ALREADY_IN_THE_PROJECT`	用户已经拥有项目访问权限	Check current user list before inviting
`UNAUTHORIZED`	执行操作的权限不足	Verify your access level and permissions
`PROJECT_NOT_FOUND`	项目不存在或没有访问权限	Confirm project ID and access rights
`INVITATION_LIMIT`	达到计费层级的邀请限制	Upgrade plan or remove inactive users
`ADD_SELF`	不能邀请自己	使用不同的电子邮件或让其他管理员邀请您
`COMPANY_BANNED`	公司账户已被暂停	Contact support to resolve account status

速率限制

用户管理操作具有以下速率限制：

邀请：每小时每公司 100 个
用户查询：每小时每用户 1000 个
角色修改：每小时每项目 50 个

概述