Roles overview

Roles are the named permission levels a member can hold. Plane ships system roles, such as admin, contributor, and guest, and a workspace can add custom roles. A custom role is built from one or more permission schemes, and its permissions are the union of theirs. A system role's permissions come from Plane's built-in definition.

The roles API is read-only. It lists the workspace's custom roles together with the system roles.

Learn more about roles and permissions

The role object

Attributes

• id string (uuid)

  Unique identifier for the role.

• name string

  Display name, for example QA Reviewer.

• slug string

  The role's key. Grants and member records refer to a role by its slug, for example as a grant's relation.

• description string

  Free-form description of what the role is for.

• namespace string

  What the role applies to. One of workspace, project, or instance.

• is_system boolean

  Whether the role is one of Plane's built-in roles.

• level integer

  A rank for comparing roles. A higher level means more access. The system roles use 30 for the instance admin, 25 for owner, 20 for admin, 15 for member and contributor, 10 for commenter, and 5 for guest.

• status string

  active or inactive.

• based_on_id string (uuid) or null

  The role this one was created from, or null.

• permission_scheme_ids array of string

  The ids of the permission schemes attached to the role, ordered by each attachment's sort order.

• permissions array of string

  Every permission the role grants, sorted, as <resource_type>:<action> strings such as workitem:edit. A permission that applies only under a condition carries the condition as a suffix, such as workitem:delete+creator. Wildcards such as * or workitem:* cover a whole set. A system role's permissions come from Plane's built-in definition. A custom role's permissions are the union of its schemes' permissions.

• updated_at string (date-time)

  When the role was last updated.

• permission_schemes array of object

  Returned only with ?expand=permission_schemes. The attached schemes, each with id, name, slug, namespace, and is_system.

Response200

{
  "id": "9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88",
  "name": "QA Reviewer",
  "slug": "qa-reviewer",
  "description": "Commenter access plus editing work items.",
  "namespace": "project",
  "is_system": false,
  "level": 10,
  "status": "active",
  "based_on_id": "6e2a9d47-1c5b-4f83-a7d0-3b8e4f1c9a62",
  "permission_scheme_ids": ["f3b8a1c6-2d7e-4a95-8c14-5e9d0b3f7a28"],
  "permissions": [
    "comment:create",
    "comment:edit+creator",
    "cycle:view",
    "module:view",
    "project:view",
    "state:view",
    "workitem:edit",
    "workitem:view"
  ],
  "updated_at": "2026-01-14T09:22:41.478363Z"
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/roles/	List roles
GET	/api/v2/workspaces/{slug}/roles/{pk}/	Get a role

Response shaping

Every role read accepts ?fields= for sparse responses and ?expand=permission_schemes to embed the attached schemes. List rows and single reads return the same fields. See Sparse fields and Expanding relations. Errors follow the shared problem+json contract.