Permissions overview

These endpoints report what you, the caller, are allowed to do. Every answer is about the principal that sends the request, so you can't ask on behalf of another user. To change who can do what on a resource, use Permission grants.

The reads come in two kinds:

• Effective permissions, at permissions/me/, summarize one workspace or one project. They return your relation there and a single list of every permission your role gives you. Use them to set up a client once, for example to hide controls a user can't use.
• Permission engine reads, at check/, resource/, accessible/, and relation/, ask about one resource or one resource type. Use them before you act on a specific record, or to find the records of a type you can act on.

Any member of the workspace can call all of them, guests included.

Learn more about roles and permissions

The effective permissions object

Both permissions/me/ routes return this object.

Attributes

• relation string or null

  Your relation on the workspace, or on the project for the project route. This is a role slug, such as admin or contributor, or the slug of a custom role. It is null when you hold no grant directly on that workspace or project.

• permission_grants array of string

  Every permission you hold at that scope, sorted. Each entry is <resource_type>:<action>, for example workitem:edit. A permission you hold only under a condition carries the condition as a suffix. For example, workitem:delete+creator applies only to work items you created. The workspace route covers every resource type. The project route covers the resource types that live in a project.

The permission engine responses

Each engine read returns a small object with one key.

• allowed boolean

  From Check a permission. Whether you can perform the action on the resource.

• permissions array of string

  From List your permissions on a resource. Action names in the form can_<action>. The list names every action the resource type supports, whatever your access.

• resource_ids array of string

  From List resources you can access. Ids of the resources of one type that you can act on.

• relation string or null

  From Get your relation to a resource. The role slug you hold directly on the resource, or null.

Response200

{
  "relation": "contributor",
  "permission_grants": [
    "cycle:create",
    "cycle:delete+creator",
    "cycle:edit+creator",
    "cycle:view",
    "module:view",
    "project:react",
    "project:view",
    "workitem:archive",
    "workitem:assign",
    "workitem:create",
    "workitem:delete+creator",
    "workitem:edit",
    "workitem:view"
  ]
}

Response200

{
  "allowed": true
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/permissions/me/	Get your effective project permissions
GET	/api/v2/workspaces/{slug}/permissions/me/	Get your effective workspace permissions
GET	/api/v2/workspaces/{slug}/permissions/check/	Check a permission
GET	/api/v2/workspaces/{slug}/permissions/resource/	List your permissions on a resource
GET	/api/v2/workspaces/{slug}/permissions/accessible/	List resources you can access
GET	/api/v2/workspaces/{slug}/permissions/relation/	Get your relation to a resource

Which read to use

Question	Read
What can I do anywhere in this workspace or project?	Effective permissions
Can I perform this action on this record?	Check a permission
Which projects, cycles, or modules can I act on?	List resources you can access
Which role was I given on this record?	Get your relation to a resource

For a single record, only Check a permission takes everything into account: your role on the record, roles inherited from its parents, teamspace access, conditions, and permissions granted or denied on the record itself. The relation and accessible reads don't count access inherited from a parent.

Response shaping

These reads return small, fixed objects. They don't take ?fields= or ?expand=. Errors follow the shared problem+json contract.