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 four operations:

• workspaceUserRoles — list the roles in one or more workspaces.
• createWorkspaceUserRole — create a 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.

RecordTagFilterInput

Limit which records a role can see based on their tags. Tags are Tag objects (Tag.title in the API).

RecordFilterInput

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

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.

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
      recordTagFilter: { enabled: true, allowedTagIds: ["tag_123"] }
    }
  ) {
    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" })
}

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.