Check a permission

GET/api/v2/workspaces/{slug}/permissions/check/

Ask whether you can perform one action on one resource. The response is a single boolean, allowed.

The answer comes from the same permission check Plane runs when you act. It counts your role on the resource and the roles you inherit from its parents, such as a workspace admin's access to every project. It also counts access through a teamspace, conditions such as +creator, and permissions granted or denied on the resource itself.

Every answer is about the caller. You can't ask on behalf of another user. Any member of the workspace can call this endpoint, guests included.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

Query Parameters

All three parameters are required. Leaving out resource_type or resource_id returns 400 with resource_type and resource_id are required. Leaving out action returns 400 with action is required.

action:requiredstring

The action to test, for example view, edit, delete, archive, or manage. Plane joins it to resource_type to form a permission such as workitem:edit.

If either name is unknown to Plane, the response is 400 with Unknown permission: <resource_type>:<action>. A known action that the resource type doesn't support, such as react on a cycle, returns "allowed": false.

resource_type:requiredstring

The kind of resource, as the permission engine names it, for example workspace, project, workitem, cycle, module, page for a project page, wiki for a workspace page, initiative, or teamspace. These are the names that prefix the permission strings in a role's permissions list. See Roles.

resource_id:requiredstring (uuid)

The id of the resource to check against. A value that isn't a UUID returns 400 with resource_id must be a UUID.

Scopes

workspaces.permissions:read

Errors

Status	Code	Cause
400	invalid_request	A parameter is missing, resource_id isn't a UUID, or resource_type and action don't name a permission.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
403	forbidden	You aren't a member of the workspace, or your token scope doesn't allow this.
404	not_found	No such workspace.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

One question per request

The action applies to the resource you name. resource_type=workitem&action=edit&resource_id=<id> asks about one work item. To see your role and everything it gives you across a whole workspace or project in one call, use Get your effective workspace permissions or Get your effective project permissions.

Check a permission

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/permissions/check/?action=edit&resource_type=project&resource_id=4af68566-94a4-4eb3-94aa-50dc9427067b" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/permissions/check/",
    headers={"X-Api-Key": "your-api-key"},
    params={
        "action": "edit",
        "resource_type": "project",
        "resource_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
    },
)
print(response.json())

const params = new URLSearchParams({
  action: "edit",
  resource_type: "project",
  resource_id: "4af68566-94a4-4eb3-94aa-50dc9427067b",
});
const response = await fetch(
  `https://api.plane.so/api/v2/workspaces/my-team/permissions/check/?${params}`,
  {
    headers: {
      "X-Api-Key": "your-api-key",
    },
  },
);
const data = await response.json();

Response200

{
  "allowed": true
}

Response400

{
  "type": "invalid_request",
  "code": "invalid_request",
  "detail": "Unknown permission: project:teleport."
}