Custom Roles

Retrieve, create, update, and delete custom user roles with granular permissions.

Custom Roles

Custom roles in Blue allow you to define precise permission sets tailored to your team’s needs. Beyond the standard access levels (OWNER, ADMIN, MEMBER, etc.), custom roles provide granular control over what users can see and do within projects.

Basic Example - List Custom Roles

Retrieve all custom roles for a project:

query GetProjectRoles {
  projectUserRoles(filter: { projectId: "web-redesign" }) {
    id
    name
    description
    allowInviteOthers
    canDeleteRecords
  }
}

Advanced Example - Create Custom Role

Create a contractor role with specific permissions:

mutation CreateContractorRole {
  createProjectUserRole(
    input: {
      projectId: "web-redesign"
      name: "External Contractor"
      description: "Limited access for external contractors"
      allowInviteOthers: false
      allowMarkRecordsAsDone: true
      canDeleteRecords: false
      showOnlyAssignedTodos: true
      isActivityEnabled: true
      isFormsEnabled: false
      isWikiEnabled: true
      isChatEnabled: false
      isDocsEnabled: true
      isFilesEnabled: true
      isRecordsEnabled: true
      isPeopleEnabled: false
    }
  ) {
    id
    name
  }
}

Available Operations

Query: projectUserRoles

Retrieve all custom roles for a project.

Input Parameters

ParameterTypeRequiredDescription
filter.projectIdStringNoProject ID or slug (if not provided, returns roles for all accessible projects)

Mutation: createProjectUserRole

Create a new custom role with specific permissions.

Input Parameters

ParameterTypeRequiredDescription
projectIdString!✅ YesProject ID or slug
nameString!✅ YesRole name
descriptionStringNoRole description
Permission Flags
allowInviteOthersBooleanNoCan invite new users (default: false)
allowMarkRecordsAsDoneBooleanNoCan complete tasks (default: false)
canDeleteRecordsBooleanNoCan delete records (default: true)
Feature Access
isActivityEnabledBooleanNoAccess to Activity section (default: true)
isChatEnabledBooleanNoAccess to Chat (default: true)
isDocsEnabledBooleanNoAccess to Docs (default: true)
isFilesEnabledBooleanNoAccess to Files (default: true)
isFormsEnabledBooleanNoAccess to Forms (default: true)
isWikiEnabledBooleanNoAccess to Wiki (default: true)
isRecordsEnabledBooleanNoAccess to Records (default: true)
isPeopleEnabledBooleanNoAccess to People section (default: true)
Visibility Settings
showOnlyAssignedTodosBooleanNoOnly see assigned tasks (default: false)
showOnlyMentionedCommentsBooleanNoOnly see mentioned comments (default: false)

Mutation: updateProjectUserRole

Update an existing custom role.

Input Parameters

Same as createProjectUserRole, plus:

ParameterTypeRequiredDescription
roleIdString!✅ YesID of the role to update

Mutation: deleteProjectUserRole

Delete a custom role.

Input Parameters

ParameterTypeRequiredDescription
roleIdString!✅ YesID of the role to delete
projectIdString!✅ YesProject ID or slug

Response Fields

ProjectUserRole Object

FieldTypeDescription
idString!Unique role identifier
nameString!Role name
descriptionStringRole description
createdAtDateTime!Creation timestamp
updatedAtDateTime!Last update timestamp
Permissions
allowInviteOthersBoolean!Can invite users
allowMarkRecordsAsDoneBoolean!Can complete tasks
canDeleteRecordsBoolean!Can delete records
Feature Flags
isActivityEnabledBoolean!Activity section access
isChatEnabledBoolean!Chat access
isDocsEnabledBoolean!Docs access
isFilesEnabledBoolean!Files access
isFormsEnabledBoolean!Forms access
isWikiEnabledBoolean!Wiki access
isRecordsEnabledBoolean!Records access
isPeopleEnabledBoolean!People section access
Visibility
showOnlyAssignedTodosBoolean!Task visibility filter
showOnlyMentionedCommentsBoolean!Comment visibility filter

Required Permissions

OperationRequired Permission
projectUserRolesAny project member
createProjectUserRoleProject OWNER or ADMIN
updateProjectUserRoleProject OWNER or ADMIN
deleteProjectUserRoleProject OWNER or ADMIN

Error Responses

Insufficient Permissions

{
  "errors": [{
    "message": "You don't have permission to manage custom roles",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

Role Not Found

{
  "errors": [{
    "message": "Custom role not found",
    "extensions": {
      "code": "PROJECT_USER_ROLE_NOT_FOUND"
    }
  }]
}

Role Limit Reached

{
  "errors": [{
    "message": "Project user role limit reached.",
    "extensions": {
      "code": "PROJECT_USER_ROLE_LIMIT"
    }
  }]
}

Important Notes

  • Default Permissions: When creating roles, unspecified boolean permissions default to false except for canDeleteRecords which defaults to true
  • Role Assignment: Assign custom roles by setting accessLevel: MEMBER and providing the roleId in the inviteUser mutation
  • Hierarchy: Custom roles are treated as MEMBER-level for hierarchy purposes
  • Role Limits: Each project can have a maximum of 20 custom roles
  • Feature Access: The feature flags control access to entire sections of the application

Use Cases

Contractor Role

{
  name: "Contractor",
  allowInviteOthers: false,
  canDeleteRecords: false,
  showOnlyAssignedTodos: true,
  isActivityEnabled: true,
  isChatEnabled: false,
  isPeopleEnabled: false
}

Department Lead

{
  name: "Department Lead",
  allowInviteOthers: true,
  allowMarkRecordsAsDone: true,
  canDeleteRecords: true,
  isActivityEnabled: true,
  isWikiEnabled: true,
  isPeopleEnabled: true
}

Read-Only Observer

{
  name: "Observer",
  allowMarkRecordsAsDone: false,
  canDeleteRecords: false,
  allowInviteOthers: false,
  showOnlyMentionedComments: true,
  isFormsEnabled: false
}