Custom Roles

Custom roles let you define precise permission sets for members of a workspace, beyond the built-in access levels. A role controls which sections a member sees (records, files, chat, docs, …), what they can do (invite, complete, delete), and—optionally—which records, lists, and fields they can view or edit. Roles are ProjectUserRole objects in the API; workspaces are Workspace objects.

You assign a role when you invite someone by passing its roleId with accessLevel: MEMBER. The role must belong to the same workspace as the invite.

This page covers five operations:

• workspaceUserRoles — list the roles in one or more workspaces.
• createWorkspaceUserRole — create a role.
• copyWorkspaceUserRole — duplicate an existing role.
• updateWorkspaceUserRole — change a role.
• deleteWorkspaceUserRole — delete a role.

Request

Send every request to https://api.blue.app/graphql with your authentication headers. Custom roles are scoped to a workspace, so pass the workspace ID (or slug) in the operation input. Company and project arguments accept either an ID or a slug.

POST https://api.blue.app/graphql
blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID

List the roles in a workspace. The filter argument is required; supply projectId for a single workspace.

query ListProjectRoles {
  workspaceUserRoles(filter: { projectId: "project_123" }) {
    id
    name
    description
    allowInviteOthers
    canDeleteRecords
    isRecordsEnabled
  }
}

To query several workspaces at once, pass projectIds instead. Either field may be null, but you must pass the filter object itself. Roles are only returned for workspaces the calling user belongs to.

query ListRolesAcrossWorkspaces {
  workspaceUserRoles(filter: { projectIds: ["project_123", "project_456"] }) {
    id
    name
    project {
      id
      name
    }
  }
}

Parameters

ProjectUserRoleFilter

The required filter argument for workspaceUserRoles.

CreateProjectUserRoleInput

The input for createWorkspaceUserRole. Only projectId and name are required; every other field is optional and falls back to the default shown.

RecordFilterInput

Restrict visible records to those matching a filter, using the same group structure as record queries.

The filter fails closed. A condition whose values are not filled in is ignored while the filter still has real conditions — but if ignoring it would leave the filter restricting nothing, the role sees no records, not every record. The same holds for a condition the workspace’s records cannot answer: it hides records rather than widening access.

showOnlyAssignedTodos combines with a caller-supplied assignee filter: in a list’s records read, the role narrows the caller’s filter (records must match it and be assigned to the member). In the workspace-level record query, it overrides the caller’s flat assigneeIds with “assigned to the member”.

CreateProjectUserRoleCustomFieldInput

Per-field access for a custom field (CustomField).

CreateProjectUserRoleTodoListInput

Per-list access for a list (RecordList).

CreateProjectUserRoleTodoFieldInput

Per-field access for a built-in record field.

TodoFieldType values: DUE_DATE, ASSIGNEE, TAG, DEPENDENCY, CUSTOM_FIELD, DESCRIPTION, CHECKLIST, REFERENCED_BY, CUSTOM_FIELD_GROUP, TIME_TRACKING, CREATED_DATE, UPDATED_DATE, COMPLETED_DATE, PROJECTS, LAST_UPDATED_BY.

CopyWorkspaceUserRoleInput

The input for copyWorkspaceUserRole.

UpdateProjectUserRoleInput

The input for updateWorkspaceUserRole. Same fields as CreateProjectUserRoleInput, with two differences:

• roleId: String! (required) — the role to update.
• projectId: String! (required) — the workspace the role belongs to, unchanged.
• name is optional here (String, not String!); omit it to keep the current name.

Any flag you omit keeps its existing value (the update merges over the stored role rather than resetting to defaults).

DeleteProjectUserRoleInput

Response

workspaceUserRoles returns an array of ProjectUserRole objects.

{
  "data": {
    "workspaceUserRoles": [
      {
        "id": "clm4n8qwx000008l0g4oxdqn7",
        "name": "External Contractor",
        "description": "Limited access for outside collaborators",
        "allowInviteOthers": false,
        "canDeleteRecords": false,
        "isRecordsEnabled": true
      }
    ]
  }
}

createWorkspaceUserRole and updateWorkspaceUserRole both return the ProjectUserRole.

{
  "data": {
    "createWorkspaceUserRole": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "External Contractor"
    }
  }
}

deleteWorkspaceUserRole returns a nullable Boolean — true on success.

{ "data": { "deleteWorkspaceUserRole": true } }

Returns — ProjectUserRole

Full example

Create a contractor role: enable the records and files sections, allow completing records but not deleting them, limit visibility to assigned records, and grant view-only access to one custom field.

mutation CreateContractorRole {
  createWorkspaceUserRole(
    input: {
      projectId: "project_123"
      name: "External Contractor"
      description: "Limited access for outside collaborators"
      isRecordsEnabled: true
      isFilesEnabled: true
      allowMarkRecordsAsDone: true
      canDeleteRecords: false
      canDeleteFiles: false
      showOnlyAssignedTodos: true
      customFields: [{ customFieldId: "field_123", viewable: true, editable: false }]
    }
  ) {
    id
    name
    isRecordsEnabled
    canDeleteRecords
  }
}

Restrict a role to records tagged tag_123 only:

mutation CreateScopedRole {
  createWorkspaceUserRole(
    input: {
      projectId: "project_123"
      name: "Client Reviewer"
      isRecordsEnabled: true
      recordFilter: { groups: [{ tagIds: ["tag_123"] }], groupLinks: [] }
    }
  ) {
    id
    name
  }
}

Rename an existing role and turn off chat without touching its other settings:

mutation UpdateRole {
  updateWorkspaceUserRole(
    input: {
      roleId: "role_123"
      projectId: "project_123"
      name: "Contractor (Phase 2)"
      isChatEnabled: false
    }
  ) {
    id
    name
    isChatEnabled
  }
}

Delete a role:

mutation DeleteRole {
  deleteWorkspaceUserRole(input: { roleId: "role_123", projectId: "project_123" })
}

Copy a role

Use copyWorkspaceUserRole to duplicate a role inside the same workspace. It returns the new WorkspaceUserRole!.

mutation CopyRole {
  copyWorkspaceUserRole(input: { projectId: "project_123", roleId: "role_123" }) {
    id
    name
    description
  }
}

{
  "data": {
    "copyWorkspaceUserRole": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Copy of Contractor",
      "description": "Limited access for external contractors"
    }
  }
}

The copy carries over every permission flag and every scoped grant on the source role: custom-field access, list access, default-field access, saved-view access, tag rules, and the record visibility filter. It does not carry over the role’s members — the copy starts with nobody assigned.

The new role is named Copy of <source name>. Because name is a 191-character column, Blue truncates the source name so the prefix fits; it does not fail on a long name. You cannot choose the name in this call — use updateWorkspaceUserRole afterwards to rename it.

A copy counts toward the workspace’s custom-role limit, so this mutation can return PLAN_LIMIT_REACHED.

Assigning a role

A role is attached to a member at invite time. Set accessLevel: MEMBER and pass the role’s roleId to inviteUser. The role’s projectId must match the invite’s workspace, or the call fails with PROJECT_USER_ROLE_NOT_FOUND. Custom roles are treated as MEMBER-level for the access hierarchy.

mutation InviteWithRole {
  inviteUser(
    input: {
      email: "contractor@example.com"
      projectId: "project_123"
      accessLevel: MEMBER
      roleId: "role_123"
    }
  )
}

Errors

The custom-role limit is plan-dependent — roughly 1 on starter plans up to ~50 on enterprise, and unlimited on some plans. Upgrade the organization’s plan to raise it.

{
  "errors": [
    {
      "message": "Custom roles per workspace limit reached (1/1). Upgrade your plan for more.",
      "extensions": {
        "code": "PLAN_LIMIT_REACHED",
        "kind": "over_limit",
        "resource": "Custom roles per workspace",
        "current": 1,
        "limit": 1
      }
    }
  ]
}

Permissions

Related

• Invite a user — assign a role via roleId.
• List users — see who has access and their roles.
• Remove a user — revoke workspace or organization access.