Groups API

Endpoints under /api/groups are the primary surface for managing the RBAC model. Frontend clients call /api/groups/me/permissions on login to bootstrap the permission cache. For the conceptual model, see Security → Users & Groups.

Endpoints

GET/api/groups🔒 auth

List all groups in the current organization. Returns an array of group objects with id, name, ldap_dn (nullable), and member_count.

POST/api/groups🔒 auth

Create a new local group. Body: {name: string, description?: string}. Returns the created group. Requires group.admin.

GET/api/groups/:id🔒 auth

Read a single group by id, including its permission grants and members.

PATCH/api/groups/:id🔒 auth

Update a group's name, description, or LDAP mapping. Requires group.admin.

DELETE/api/groups/:id🔒 auth

Delete a group. Members lose any permissions granted only through this group. Requires group.admin.

POST/api/groups/:id/permissions🔒 auth

Grant a permission to a group. Body: {permission_type: string, target_id?: string}. See the Permissions Reference for valid permission_type strings.

DELETE/api/groups/:id/permissions/:permission_id🔒 auth

Revoke a specific permission grant from a group.

GET/api/groups/me/permissions🔒 auth

Return the flattened permission set for the currently authenticated user, computed from all group memberships. Used by the frontend usePermission() hook to bootstrap the permission cache on login.

Membership

POST/api/groups/:id/members🔒 auth

Add a user to a group. Body: {user_id: string}.

DELETE/api/groups/:id/members/:user_id🔒 auth

Remove a user from a group.

LDAP-mapped groups

When a group has a non-null ldap_dn, membership is read from the directory server and cannot be modified via the membership endpoints — those return 409 Conflict. To change membership of an LDAP-mapped group, modify the directory and wait for the next sync cycle.