List permissions
list_permissionsCheck which actions the current user can perform, globally or within a project. Use it to prevent 403 errors, explain failures, or choose the right tool by querying real capabilities.
Instructions
List what the authenticated user is allowed to do, globally or in one project.
Use it before attempting a write that might 403, to explain to a user why an action failed, or to pick between tools ("can I add a member here, or should I ask an admin?"). It reads the real capabilities API for the current user — it does not return a user profile and it never guesses from the admin flag.
Returns the standard list envelope whose items are one row per context —
{id, context, project, actions} with actions such as
work_packages/create — plus principal (the user asked about),
capability_count, and check when permission was given.
CAVEAT, straight from the API: OpenProject exposes only a SUBSET of its permissions as capabilities. An action missing from this list is not proof that the user lacks the permission — it may simply not be modelled. Treat a hit as reliable and a miss as "unknown, try it and read the 403".
Pitfalls: the capabilities API has no "me" value, so the numeric id of the
authenticated user is resolved first (from the cached users/me) — you cannot ask
about another user with this tool. Results are capped at 500 capabilities with a note
in notes when the cap is hit; scope with project_id to stay well under it.
Capabilities are about permission only: a permitted action can still fail validation.
Cross-references: get_instance_info reports who this server is authenticated as
and what the instance version supports; list_memberships and list_roles show
where the permissions come from; get_project_metadata lists the ids a permitted
action needs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| permission | No | Optional single action to check, spelled the way OpenProject does: '<resource>/<action>', e.g. 'work_packages/create', 'memberships/create', 'projects/update'. Adds a {checked, allowed, granted_in} predicate to the result; the full grouped listing is returned either way, so you can see the exact spellings this instance uses. | |
| project_id | No | Numeric project id or URL identifier to scope the question to that project ('may I create work packages HERE'). Omit it for the instance-wide (global) actions such as creating projects or administering users. An identifier is resolved to its numeric id first, because the capabilities API only accepts numeric project ids. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| check | No | Present only when the 'permission' parameter was given. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| principal | Yes | The user the capabilities were resolved for — always the authenticated account, by numeric id. | |
| pagination | Yes | Total/page/page_size/has_more. | |
| capability_count | No | Individual capabilities read from the API before grouping. |