---

Resumen

La API de Gestión de Usuarios proporciona herramientas integrales para gestionar miembros del equipo, controlar permisos de acceso y organizar su fuerza laboral en proyectos y empresas de Blue. Ya sea que esté agregando nuevos miembros al equipo, gestionando usuarios existentes o definiendo estructuras de permisos personalizadas, estas API manejan todos los aspectos de la gestión del ciclo de vida del usuario.

La gestión de usuarios en Blue opera en dos niveles:

• Nivel de proyecto: Gestionar usuarios dentro de proyectos específicos con permisos específicos del proyecto
• Nivel de empresa: Gestionar usuarios en toda su organización con acceso a nivel de empresa

Operaciones Disponibles

Gestión de Usuarios Básica

Operación	Descripción	Enlace
Invite User	Enviar invitaciones a nuevos usuarios con niveles de acceso específicos	View Details →
List Users	Consultar y filtrar usuarios en proyectos o empresas	View Details →
Remove User	Eliminar usuarios de proyectos o empresas	View Details →

Gestión de Roles y Permisos

Operación	Descripción	Enlace
Custom Roles	Crear y gestionar roles personalizados con permisos granulares	View Details →

Niveles de Acceso

Blue proporciona un sistema de permisos jerárquico con niveles de acceso predefinidos:

Niveles de Acceso Estándar

Nivel	Descripción	Capacidades
OWNER	Control total sobre proyecto/empresa	All permissions, can transfer ownership
ADMIN	Acceso administrativo	User management, settings, billing
MEMBER	Miembro estándar del equipo	Full project functionality, limited admin access
CLIENT	Acceso de cliente externo	Limited project visibility, focused on deliverables
COMMENT_ONLY	Acceso solo para comentarios	Puede ver y comentar, no puede editar
VIEW_ONLY	Acceso solo de lectura	Can view content only

Jerarquía de Permisos

Los usuarios solo pueden invitar o gestionar usuarios en su nivel o por debajo:

• PROPIETARIOS pueden gestionar todos los niveles de acceso
• ADMINISTRADORES pueden gestionar ADMIN, MIEMBRO, CLIENTE, SOLO_COMENTARIOS, SOLO_VISTA
• MIEMBROS pueden gestionar MIEMBRO, CLIENTE, SOLO_COMENTARIOS, SOLO_VISTA
• CLIENTES solo pueden gestionar a otros CLIENTES

Conceptos Clave

Invitaciones de Usuarios

• Basadas en correo electrónico: Los usuarios son invitados a través de la dirección de correo electrónico
• Asignación de roles: Establecer nivel de acceso y rol personalizado opcional durante la invitación
• Multi-proyecto: Una sola invitación puede otorgar acceso a múltiples proyectos
• Expiración: Las invitaciones expiran después de 7 días
• Notificaciones automáticas: Blue envía invitaciones por correo electrónico automáticamente

Acceso de Proyecto vs Empresa

• Invitación de proyecto: Otorga acceso solo a un proyecto específico
• Invitación de empresa: Otorga acceso a nivel de empresa, incluyendo opcionalmente proyectos específicos
• Propietarios de la empresa: Obtienen automáticamente acceso ADMIN a todos los proyectos de la empresa
• Restricciones de alcance: No se pueden combinar parámetros de invitación de proyecto y empresa

Roles Personalizados

• Permisos granulares: Definir capacidades específicas más allá de los niveles de acceso estándar
• Específicos de proyecto: Los roles personalizados están limitados a proyectos individuales
• Control a nivel de campo: Controlar el acceso a campos personalizados específicos
• Restricciones de acción: Limitar acciones específicas (crear, editar, eliminar, etc.)

Patrones Comunes

Invitar a un Nuevo Miembro del Equipo

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

Crear una Invitación a Nivel de Empresa

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

Listar Usuarios de Proyecto

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

Eliminar un Usuario

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

Crear un Rol Personalizado

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

Gestión de Permisos

Matriz de Permisos Estándar

Acción	PROPIETARIO	ADMINISTRADOR	MIEMBRO	CLIENTE	SOLO_COMENTARIOS	SOLO_VISTA
Invite Users	✅ Todos los niveles	✅ ADMIN y por debajo	✅ MIEMBRO y por debajo	✅ Solo CLIENTE	❌ No	❌ No
Remove Users	✅ Todos los usuarios	✅ ADMIN y por debajo	✅ MIEMBRO y por debajo	✅ Solo CLIENTE	❌ No	❌ No
Modify Project Settings	✅ Sí	✅ Sí	❌ No	❌ No	❌ No	❌ No
Create Records	✅ Sí	✅ Sí	✅ Sí	✅ Limitado	❌ No	❌ No
Edit All Records	✅ Sí	✅ Sí	✅ Sí	❌ No	❌ No	❌ No
Delete Records	✅ Sí	✅ Sí	✅ Sí	❌ No	❌ No	❌ No
View Reports	✅ Sí	✅ Sí	✅ Sí	✅ Limitado	❌ No	❌ No

Capacidades de Rol Personalizado

• Permisos a nivel de campo: Controlar el acceso a campos personalizados específicos
• Reglas específicas de acción: Permitir/denegar operaciones específicas (crear, editar, eliminar)
• Restricciones de vista: Limitar qué registros pueden ver los usuarios
• Activación de funciones: Habilitar/deshabilitar funciones específicas por rol

Mejores Prácticas

Incorporación de Usuarios

1. Comience con roles estándar - Utilice niveles de acceso predefinidos para la mayoría de los usuarios
2. Permisos progresivos - Comience con acceso limitado, expanda según sea necesario
3. Comunicación clara - Incluya contexto al enviar invitaciones
4. Revisiones regulares - Audite el acceso de usuarios periódicamente

Consideraciones de Seguridad

1. Principio de menor privilegio - Otorgue los permisos mínimos necesarios
2. Auditorías de acceso regulares - Revise los permisos de los usuarios trimestralmente
3. Proceso de desvinculación - Elimine el acceso inmediatamente cuando los usuarios se vayan
4. Documentación de roles personalizados - Documente los propósitos y limitaciones de los roles personalizados

Organización del Equipo

1. Nomenclatura consistente - Utilice nombres de roles claros y descriptivos
2. Consolidación de roles - Evite crear demasiados roles personalizados similares
3. Estructura de la empresa - Alinee los permisos con la jerarquía organizacional
4. Herencia de proyectos - Considere cómo los roles de la empresa afectan el acceso a los proyectos

Manejo de Errores

Errores comunes al gestionar usuarios:

Código de Error	Descripción	Solución
USER_ALREADY_IN_THE_PROJECT	El usuario ya tiene acceso al proyecto	Check current user list before inviting
UNAUTHORIZED	Permisos insuficientes para realizar la acción	Verify your access level and permissions
PROJECT_NOT_FOUND	El proyecto no existe o no hay acceso	Confirm project ID and access rights
INVITATION_LIMIT	Se alcanzó el límite de invitaciones para el nivel de facturación	Upgrade plan or remove inactive users
ADD_SELF	No se puede invitar a uno mismo	Utilice un correo electrónico diferente o pida a otro administrador que lo invite
COMPANY_BANNED	La cuenta de la empresa está suspendida	Contact support to resolve account status

Límites de Tasa

Las operaciones de gestión de usuarios tienen los siguientes límites de tasa:

• Invitaciones: 100 por hora por empresa
• Consultas de usuarios: 1000 por hora por usuario
• Modificaciones de roles: 50 por hora por proyecto

Recursos Relacionados

• API de Proyectos - Gestión de proyectos que contienen usuarios
• API de Registros - Comprender cómo los permisos de usuario afectan el acceso a los registros
• API de Automatizaciones - Automatización de flujos de trabajo de gestión de usuarios
• API de Campos Personalizados - Gestión de permisos a nivel de campo para roles personalizados