Groups API

Groups organize users for authorization inside a tenant. Groups support nesting (parentGroupId), so you can mirror departments or business units, and they can carry arbitrary attributes for custom claims or integrations. Groups are managed in the console under Groups, and every group can be bound to platform roles.

All endpoints require the x-tenant header and the admin:all permission unless noted otherwise.

Groups are the right tool for coarse authorization (whole teams). For object-level decisions (“can this user edit this record?”) use Fine-Grained Authorization instead.

Group CRUD

GET/api/groupsRequires: admin:all

List all groups in the tenant.

POST/api/groupsRequires: admin:all

Create a group. Body: name (required), parentGroupId (optional, for nested groups), attributes (optional object of custom key/values). Returns { success, data: { id } }.

GET/api/groups/[id]Requires: admin:all

Fetch a single group with its members and assigned roles.

PUT/api/groups/[id]Requires: admin:all

Update a group’s name, parent, or attributes.

DELETE/api/groups/[id]Requires: admin:all

Delete the group. Membership bindings are removed; users themselves are not deleted.

Membership

GET/api/groups/[id]/membersRequires: admin:all

List the users that belong to the group.

POST/api/groups/[id]/membersRequires: admin:all

Add a user to the group. Body: { "userId": "..." } (required).

DELETE/api/groups/[id]/membersRequires: admin:all

Remove a user from the group.

Group roles

GET/api/groups/[id]/rolesRequires: admin:all

List the platform roles assigned to the group.

POST/api/groups/[id]/rolesRequires: admin:all

Assign roles to the group. Body: { "roles": [{ "name": "..." }] } — a non-empty array is required.

Role hierarchy is enforced. The caller can only assign roles with a strictly lower priority than their own highest-priority role. Attempting to assign a role at or above your own priority is rejected.

Versioned access

Groups are also covered by the /api/v1 envelope layer, which guarantees the canonical { ok, data } response shape for list/get/create/update/delete operations.