사용자 관리 API

Blue 프로젝트 및 회사에서 사용자, 초대, 역할 및 권한을 관리하기 위한 완전한 API 참조

개요

사용자 관리 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

권한 계층 구조

사용자는 자신의 수준 또는 그 이하의 사용자만 초대하거나 관리할 수 있습니다:

소유자는 모든 접근 수준을 관리할 수 있습니다.
관리자는 ADMIN, MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY를 관리할 수 있습니다.
구성원은 MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY를 관리할 수 있습니다.
클라이언트는 다른 CLIENT만 관리할 수 있습니다.

주요 개념

사용자 초대

이메일 기반: 사용자는 이메일 주소를 통해 초대됩니다.
역할 할당: 초대 시 접근 수준 및 선택적 사용자 정의 역할을 설정합니다.
다중 프로젝트: 단일 초대가 여러 프로젝트에 대한 접근을 부여할 수 있습니다.
만료: 초대는 7일 후에 만료됩니다.
자동 알림: Blue는 이메일 초대를 자동으로 보냅니다.

프로젝트 대 회사 접근

프로젝트 초대: 특정 프로젝트에만 접근을 부여합니다.
회사 초대: 회사 수준의 접근을 부여하며, 선택적으로 특정 프로젝트를 포함할 수 있습니다.
회사 소유자: 모든 회사 프로젝트에 대해 자동으로 ADMIN 접근 권한을 얻습니다.
범위 제한: 프로젝트 및 회사 초대 매개변수를 결합할 수 없습니다.

사용자 정의 역할

세분화된 권한: 표준 접근 수준을 넘어서는 특정 기능을 정의합니다.
프로젝트 특정: 사용자 정의 역할은 개별 프로젝트에 한정됩니다.
필드 수준 제어: 특정 사용자 정의 필드에 대한 접근을 제어합니다.
작업 제한: 특정 작업(생성, 편집, 삭제 등)을 제한합니다.

일반 패턴

새로운 팀 구성원 초대

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	✅ 모든 수준	✅ ADMIN 이하	✅ MEMBER 이하	✅ CLIENT만	❌ 없음	❌ 없음
Remove Users	✅ 모든 사용자	✅ ADMIN 이하	✅ MEMBER 이하	✅ CLIENT만	❌ 없음	❌ 없음
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회

개요