---

Visão Geral

A API de Gerenciamento de Usuários fornece ferramentas abrangentes para gerenciar membros da equipe, controlar permissões de acesso e organizar sua força de trabalho em projetos e empresas Blue. Se você está adicionando novos membros à equipe, gerenciando usuários existentes ou definindo estruturas de permissão personalizadas, essas APIs lidam com todos os aspectos do gerenciamento do ciclo de vida do usuário.

O gerenciamento de usuários na Blue opera em dois níveis:

• Nível de projeto: Gerencie usuários dentro de projetos específicos com permissões específicas do projeto
• Nível de empresa: Gerencie usuários em toda a sua organização com acesso em toda a empresa

Operações Disponíveis

Gerenciamento de Usuários Core

Operação	Descrição	Link
Invite User	Enviar convites para novos usuários com níveis de acesso específicos	View Details →
List Users	Consultar e filtrar usuários em projetos ou empresas	View Details →
Remove User	Remover usuários de projetos ou empresas	View Details →

Gerenciamento de Funções e Permissões

Operação	Descrição	Link
Custom Roles	Criar e gerenciar funções personalizadas com permissões granulares	View Details →

Níveis de Acesso

A Blue fornece um sistema de permissões hierárquico com níveis de acesso predefinidos:

Níveis de Acesso Padrão

Nível	Descrição	Capacidades
OWNER	Controle total sobre projeto/empresa	All permissions, can transfer ownership
ADMIN	Acesso administrativo	User management, settings, billing
MEMBER	Membro padrão da equipe	Full project functionality, limited admin access
CLIENT	Acesso de cliente externo	Limited project visibility, focused on deliverables
COMMENT_ONLY	Acesso somente para comentários	Pode visualizar e comentar, não pode editar
VIEW_ONLY	Acesso somente para leitura	Can view content only

Hierarquia de Permissões

Os usuários só podem convidar ou gerenciar usuários em seu nível ou abaixo:

• PROPRIETÁRIOS podem gerenciar todos os níveis de acesso
• ADMINS podem gerenciar ADMIN, MEMBRO, CLIENTE, SOMENTE_COMENTÁRIO, SOMENTE_VISUALIZAÇÃO
• MEMBROS podem gerenciar MEMBRO, CLIENTE, SOMENTE_COMENTÁRIO, SOMENTE_VISUALIZAÇÃO
• CLIENTES podem apenas gerenciar outros CLIENTES

Conceitos Chave

Convites de Usuário

• Baseado em e-mail: Usuários são convidados através do endereço de e-mail
• Atribuição de função: Defina o nível de acesso e uma função personalizada opcional durante o convite
• Multi-projeto: Um único convite pode conceder acesso a vários projetos
• Expiração: Convites expiram após 7 dias
• Notificações automáticas: A Blue envia convites por e-mail automaticamente

Acesso de Projeto vs Empresa

• Convite de projeto: Concede acesso apenas ao projeto específico
• Convite de empresa: Concede acesso em nível de empresa, opcionalmente incluindo projetos específicos
• Proprietários da empresa: Obtêm automaticamente acesso ADMIN a todos os projetos da empresa
• Restrições de escopo: Não é possível combinar parâmetros de convite de projeto e empresa

Funções Personalizadas

• Permissões granulares: Defina capacidades específicas além dos níveis de acesso padrão
• Específico do projeto: Funções personalizadas são limitadas a projetos individuais
• Controle em nível de campo: Controle o acesso a campos personalizados específicos
• Restrições de ação: Limite ações específicas (criar, editar, excluir, etc.)

Padrões Comuns

Convidando um Novo Membro da Equipe

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

Criando um Convite para Toda a Empresa

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

Listando Usuários do Projeto

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

Removendo um Usuário

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

Criando uma Função Personalizada

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
  }
}

Gerenciamento de Permissões

Matriz de Permissões Padrão

Ação	PROPRIETÁRIO	ADMIN	MEMBRO	CLIENTE	SOMENTE_COMENTÁRIO	SOMENTE_VISUALIZAÇÃO
Invite Users	✅ Todos os níveis	✅ ADMIN e abaixo	✅ MEMBRO e abaixo	✅ CLIENTE apenas	❌ Não	❌ Não
Remove Users	✅ Todos os usuários	✅ ADMIN e abaixo	✅ MEMBRO e abaixo	✅ CLIENTE apenas	❌ Não	❌ Não
Modify Project Settings	✅ Sim	✅ Sim	❌ Não	❌ Não	❌ Não	❌ Não
Create Records	✅ Sim	✅ Sim	✅ Sim	✅ Limitado	❌ Não	❌ Não
Edit All Records	✅ Sim	✅ Sim	✅ Sim	❌ Não	❌ Não	❌ Não
Delete Records	✅ Sim	✅ Sim	✅ Sim	❌ Não	❌ Não	❌ Não
View Reports	✅ Sim	✅ Sim	✅ Sim	✅ Limitado	❌ Não	❌ Não

Capacidades de Funções Personalizadas

• Permissões em nível de campo: Controle o acesso a campos personalizados específicos
• Regras específicas de ação: Permitir/negar operações específicas (criar, editar, excluir)
• Restrições de visualização: Limite quais registros os usuários podem ver
• Alternância de recursos: Ativar/desativar recursos específicos por função

Melhores Práticas

Integração de Usuários

1. Comece com funções padrão - Use níveis de acesso predefinidos para a maioria dos usuários
2. Permissões progressivas - Comece com acesso limitado, expanda conforme necessário
3. Comunicação clara - Inclua contexto ao enviar convites
4. Revisões regulares - Audite o acesso dos usuários periodicamente

Considerações de Segurança

1. Princípio do menor privilégio - Conceda as permissões mínimas necessárias
2. Auditorias de acesso regulares - Revise as permissões dos usuários trimestralmente
3. Processo de desligamento - Remova o acesso imediatamente quando os usuários saírem
4. Documentação de funções personalizadas - Documente os propósitos e limitações das funções personalizadas

Organização da Equipe

1. Nomenclatura consistente - Use nomes de funções claros e descritivos
2. Consolidação de funções - Evite criar muitas funções personalizadas semelhantes
3. Estrutura da empresa - Alinhe permissões com a hierarquia organizacional
4. Herdabilidade de projetos - Considere como as funções da empresa afetam o acesso ao projeto

Tratamento de Erros

Erros comuns ao gerenciar usuários:

Código de Erro	Descrição	Solução
USER_ALREADY_IN_THE_PROJECT	Usuário já tem acesso ao projeto	Check current user list before inviting
UNAUTHORIZED	Permissões insuficientes para realizar a ação	Verify your access level and permissions
PROJECT_NOT_FOUND	O projeto não existe ou não há acesso	Confirm project ID and access rights
INVITATION_LIMIT	Limite de convites atingido para o nível de faturamento	Upgrade plan or remove inactive users
ADD_SELF	Não é possível convidar a si mesmo	Use um e-mail diferente ou peça a outro administrador para convidá-lo
COMPANY_BANNED	Conta da empresa está suspensa	Contact support to resolve account status

Limites de Taxa

As operações de gerenciamento de usuários têm os seguintes limites de taxa:

• Convites: 100 por hora por empresa
• Consultas de usuários: 1000 por hora por usuário
• Modificações de função: 50 por hora por projeto

Recursos Relacionados

• API de Projetos - Gerenciando projetos que contêm usuários
• API de Registros - Entendendo como as permissões de usuário afetam o acesso a registros
• API de Automação - Automatizando fluxos de trabalho de gerenciamento de usuários
• API de Campos Personalizados - Gerenciando permissões em nível de campo para funções personalizadas