List project memberships
list_membershipsList memberships per project and principal, showing roles and access, to audit who can reach what, verify roles before granting or revoking access, and find all projects a user can see.
Instructions
List who has access to which project, and with which roles.
Use it before granting or revoking access ("does she already have a role here?"), to audit a project's member list, or to see which projects a principal can reach. Called with no arguments it pages through every membership the authenticated account may see, which on a large instance is a lot — filter.
Returns the standard list envelope: items of {id, project, principal {id,name,type}, roles[], created_at, updated_at} plus
pagination{total,page,page_size,has_more}.
Pitfalls. The id in each row is the membership id — the handle for
update_membership and delete_membership — not the principal id and
not the project id; mixing them up revokes the wrong access. A person
can also reach a project through a group membership, so an empty
result for principal_id does not prove they have no access. Memberships
say who may act, not what they may do: roles carry the permissions.
Cross-references: list_roles for role ids and their permissions;
create_membership / update_membership / delete_membership to change
access (admin-gated); search_principals for principal ids;
list_permissions for what the current user may do.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| page_size | No | Memberships per page, 1-100. | |
| project_id | No | Only memberships in this project. Numeric id or the URL identifier (an identifier costs one extra lookup). Combine with principal_id to check one person's roles in one project. | |
| principal_id | No | Only memberships held by this principal — a user, group or placeholder-user id from search_principals. Use it to answer 'which projects can this person see'. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |