Skip to main content

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.