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

Иерархия разрешений

Пользователи могут приглашать или управлять пользователями только на своем уровне или ниже:

ВЛАДЕЛЬЦЫ могут управлять всеми уровнями доступа
АДМИНЫ могут управлять ADMIN, MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY
ЧЛЕНЫ могут управлять MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY
КЛИЕНТЫ могут управлять только другими КЛИЕНТАМИ

Ключевые концепции

Приглашения пользователей

По электронной почте: Пользователи приглашаются по адресу электронной почты
Назначение роли: Установите уровень доступа и необязательную пользовательскую роль во время приглашения
Многофункциональные проекты: Одно приглашение может предоставить доступ к нескольким проектам
Истечение срока действия: Приглашения истекают через 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 в час на проект

Связанные ресурсы

API проектов - Управление проектами, содержащими пользователей
API записей - Понимание того, как разрешения пользователей влияют на доступ к записям
API автоматизации - Автоматизация рабочих процессов управления пользователями
API пользовательских полей - Управление разрешениями на уровне полей для пользовательских ролей