Groups¶

Overview¶

Groups are named collections of users. They are used to:

Grant batch access to applications (access_restricted apps)
Assign Admin roles to multiple users at once
Assign app role mappings to multiple users at once
Delegate group membership management to non-admin users (Group Managers)

Creating a group¶

UI: Administration → Groups → + Create Group

API:

POST /api/v1/groups
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Engineering",
  "description": "Engineering department"
}

Managing members¶

Add a member¶

POST /api/v1/groups/{id}/members
{ "user_id": "<uuid>" }

Remove a member¶

DELETE /api/v1/groups/{id}/members/{userId}

List members¶

Returns a paginated list of group members.

GET /api/v1/groups/{id}/members

Query parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Page size (default: 20)
`search`	string	Filter by email, username or display name

Response:

{
  "data": [...],
  "total": 42,
  "page": 1,
  "limit": 20
}

Group Managers¶

A group can have managers — users or other groups whose members are permitted to add and remove members from the group, without needing any IDP administrative role.

Managers are added by users with the groups.update permission:

POST /api/v1/groups/{id}/managers
{ "subject_type": "user", "subject_id": "<uuid>" }

subject_type can be "user" or "group".

Group managers see their manageable groups under Group Membership in the UI (accessible from the sidebar).

Assigning Admin roles to a group¶

All members of the group inherit the permissions of the assigned Admin role:

POST /api/v1/groups/{id}/admin-roles
{ "role_id": "<uuid>" }

Application access¶

When an application has access_restricted = true, only explicitly granted users and groups can authenticate against it. Grant group access:

POST /api/v1/applications/{appId}/access/groups
{ "group_id": "<uuid>" }

`${groups}` in claims and attributes¶

The ${groups} template variable resolves to the authenticated user's full list of group names. This can be used in OIDC claim mappings and SAML attribute mappings.

See Claim Mappings for details.