---

Overview

The User Management API provides comprehensive tools for managing team members, controlling access permissions, and organizing your workforce across Blue projects and companies. Whether you're adding new team members, managing existing users, or defining custom permission structures, these APIs handle all aspects of user lifecycle management.

User management in Blue operates at two levels:

• Project-level: Manage users within specific projects with project-specific permissions
• Company-level: Manage users across your entire organization with company-wide access

Available Operations

Core User Management

Operation	Description	Link
Invite User	Send invitations to new users with specific access levels	View Details →
List Users	Query and filter users in projects or companies	View Details →
Remove User	Remove users from projects or companies	View Details →

Role and Permission Management

Operation	Description	Link
Custom Roles	Create and manage custom roles with granular permissions	View Details →

Access Levels

Blue provides a hierarchical permission system with predefined access levels:

Standard Access Levels

Level	Description	Capabilities
OWNER	Full control over project/company	All permissions, can transfer ownership
ADMIN	Administrative access	User management, settings, billing
MEMBER	Standard team member	Full project functionality, limited admin access
CLIENT	External client access	Limited project visibility, focused on deliverables
COMMENT_ONLY	Comment-only access	Can view and comment, cannot edit
VIEW_ONLY	Read-only access	Can view content only

Permission Hierarchy

Users can only invite or manage users at their level or below:

• OWNERS can manage all access levels
• ADMINS can manage ADMIN, MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY
• MEMBERS can manage MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY
• CLIENTS can only manage other CLIENTS

Key Concepts

User Invitations

• Email-based: Users are invited via email address
• Role assignment: Set access level and optional custom role during invitation
• Multi-project: Single invitation can grant access to multiple projects
• Expiration: Invitations expire after 7 days
• Automatic notifications: Blue sends email invitations automatically

Project vs Company Access

• Project invitation: Grants access to specific project only
• Company invitation: Grants company-level access, optionally including specific projects
• Company owners: Automatically get ADMIN access to all company projects
• Scope restrictions: Cannot combine project and company invitation parameters

Custom Roles

• Granular permissions: Define specific capabilities beyond standard access levels
• Project-specific: Custom roles are scoped to individual projects
• Field-level control: Control access to specific custom fields
• Action restrictions: Limit specific actions (create, edit, delete, etc.)

Common Patterns

Inviting a New Team Member

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

Creating a Company-Wide Invitation

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

Listing Project Users

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

Removing a User

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

Creating a Custom Role

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

Permission Management

Standard Permissions Matrix

Action	OWNER	ADMIN	MEMBER	CLIENT	COMMENT_ONLY	VIEW_ONLY
Invite Users	✅ All levels	✅ ADMIN and below	✅ MEMBER and below	✅ CLIENT only	❌ No	❌ No
Remove Users	✅ All users	✅ ADMIN and below	✅ MEMBER and below	✅ CLIENT only	❌ No	❌ No
Modify Project Settings	✅ Yes	✅ Yes	❌ No	❌ No	❌ No	❌ No
Create Records	✅ Yes	✅ Yes	✅ Yes	✅ Limited	❌ No	❌ No
Edit All Records	✅ Yes	✅ Yes	✅ Yes	❌ No	❌ No	❌ No
Delete Records	✅ Yes	✅ Yes	✅ Yes	❌ No	❌ No	❌ No
View Reports	✅ Yes	✅ Yes	✅ Yes	✅ Limited	❌ No	❌ No

Custom Role Capabilities

• Field-level permissions: Control access to specific custom fields
• Action-specific rules: Allow/deny specific operations (create, edit, delete)
• View restrictions: Limit which records users can see
• Feature toggles: Enable/disable specific features per role

Best Practices

User Onboarding

1. Start with standard roles - Use predefined access levels for most users
2. Progressive permissions - Begin with limited access, expand as needed
3. Clear communication - Include context when sending invitations
4. Regular reviews - Audit user access periodically

Security Considerations

1. Principle of least privilege - Grant minimum necessary permissions
2. Regular access audits - Review user permissions quarterly
3. Offboarding process - Remove access immediately when users leave
4. Custom role documentation - Document custom role purposes and limitations

Team Organization

1. Consistent naming - Use clear, descriptive role names
2. Role consolidation - Avoid creating too many similar custom roles
3. Company structure - Align permissions with organizational hierarchy
4. Project inheritance - Consider how company roles affect project access

Error Handling

Common errors when managing users:

Error Code	Description	Solution
USER_ALREADY_IN_THE_PROJECT	User already has project access	Check current user list before inviting
UNAUTHORIZED	Insufficient permissions to perform action	Verify your access level and permissions
PROJECT_NOT_FOUND	Project doesn't exist or no access	Confirm project ID and access rights
INVITATION_LIMIT	Reached invitation limit for billing tier	Upgrade plan or remove inactive users
ADD_SELF	Cannot invite yourself	Use a different email or have another admin invite you
COMPANY_BANNED	Company account is suspended	Contact support to resolve account status

Rate Limits

User management operations have the following rate limits:

• Invitations: 100 per hour per company
• User queries: 1000 per hour per user
• Role modifications: 50 per hour per project

Related Resources

• Projects API - Managing projects that contain users
• Records API - Understanding how user permissions affect record access
• Automations API - Automating user management workflows
• Custom Fields API - Managing field-level permissions for custom roles