0
# Group Management
1

2
Group hierarchy management, member administration, and group-based role assignments.
3

4
## Capabilities
5

6
### Group CRUD Operations
7

8
Basic group lifecycle management with hierarchical organization.
9

10
```typescript { .api }
11
/**
12
 * Find groups with optional search and pagination
13
 * @param query - Optional search and pagination parameters
14
 * @returns Array of group representations
15
 */
16
find(query?: GroupQuery): Promise<GroupRepresentation[]>;
17

18
/**
19
 * Create a new group
20
 * @param group - Group configuration
21
 * @returns Object with created group ID
22
 */
23
create(group: GroupRepresentation): Promise<{ id: string }>;
24

25
/**
26
 * Find a specific group by ID
27
 * @param params - Group identifier
28
 * @returns Group representation or undefined if not found
29
 */
30
findOne(params: { id: string }): Promise<GroupRepresentation | undefined>;
31

32
/**
33
 * Update an existing group
34
 * @param query - Group identifier
35
 * @param group - Updated group configuration
36
 */
37
update(query: { id: string }, group: GroupRepresentation): Promise<void>;
38

39
/**
40
 * Delete a group
41
 * @param params - Group identifier
42
 */
43
del(params: { id: string }): Promise<void>;
44

45
/**
46
 * Count groups with optional search criteria
47
 * @param query - Optional search parameters
48
 * @returns Object with count
49
 */
50
count(query?: GroupCountQuery): Promise<{ count: number }>;
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
// Find all groups
57
const groups = await kcAdminClient.groups.find();
58
console.log("Available groups:", groups.map(g => g.name));
59

60
// Search groups with pagination
61
const searchResult = await kcAdminClient.groups.find({
62
  search: "admin",
63
  first: 0,
64
  max: 10,
65
  briefRepresentation: true,
66
});
67

68
// Create new group
69
const { id } = await kcAdminClient.groups.create({
70
  name: "developers",
71
  attributes: {
72
    department: ["engineering"],
73
    location: ["remote"],
74
  },
75
});
76

77
// Update group
78
await kcAdminClient.groups.update(
79
  { id },
80
  {
81
    name: "senior-developers",
82
    attributes: {
83
      department: ["engineering"],
84
      level: ["senior"],
85
    },
86
  }
87
);
88

89
// Get group count
90
const { count } = await kcAdminClient.groups.count({
91
  search: "dev",
92
});
93
console.log("Groups containing 'dev':", count);
94
```
95

96
### Group Hierarchy
97

98
Management of parent-child group relationships and subgroup operations.
99

100
```typescript { .api }
101
/**
102
 * List subgroups of a parent group
103
 * @param query - Parent group ID and optional pagination
104
 * @returns Array of subgroup representations
105
 */
106
listSubGroups(query: SubGroupQuery): Promise<GroupRepresentation[]>;
107

108
/**
109
 * Create or update a child group under a parent
110
 * @param query - Parent group identifier
111
 * @param group - Child group configuration
112
 * @returns Object with created/updated group ID
113
 */
114
setOrCreateChild(query: { id: string }, group: GroupRepresentation): Promise<{ id: string }>;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
// List subgroups
121
const subgroups = await kcAdminClient.groups.listSubGroups({
122
  parentId: parentGroupId,
123
  first: 0,
124
  max: 20,
125
});
126

127
console.log("Subgroups:", subgroups.map(g => g.name));
128

129
// Create child group
130
const { id: childId } = await kcAdminClient.groups.setOrCreateChild(
131
  { id: parentGroupId },
132
  {
133
    name: "frontend-team",
134
    attributes: {
135
      specialty: ["react", "typescript"],
136
    },
137
  }
138
);
139

140
// Create nested hierarchy
141
const { id: grandparentId } = await kcAdminClient.groups.create({
142
  name: "engineering",
143
});
144

145
const { id: parentId } = await kcAdminClient.groups.setOrCreateChild(
146
  { id: grandparentId },
147
  { name: "development" }
148
);
149

150
await kcAdminClient.groups.setOrCreateChild(
151
  { id: parentId },
152
  { name: "backend-team" }
153
);
154
```
155

156
### Group Members
157

158
Management of group membership and user assignments.
159

160
```typescript { .api }
161
/**
162
 * List members of a group
163
 * @param params - Group identifier and pagination options
164
 * @returns Array of user representations
165
 */
166
listMembers(params: { id: string } & PaginatedQuery): Promise<UserRepresentation[]>;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
// Get all group members
173
const members = await kcAdminClient.groups.listMembers({
174
  id: groupId,
175
});
176

177
console.log("Group members:", members.map(u => u.username));
178

179
// Get group members with pagination
180
const memberPage = await kcAdminClient.groups.listMembers({
181
  id: groupId,
182
  first: 0,
183
  max: 50,
184
});
185

186
// Count group members
187
const allMembers = await kcAdminClient.groups.listMembers({ id: groupId });
188
console.log("Total members:", allMembers.length);
189
```
190

191
### Group Role Mappings
192

193
Role assignment and management for groups (similar to user role mappings).
194

195
```typescript { .api }
196
/**
197
 * List all role mappings for a group
198
 * @param params - Group identifier
199
 * @returns Complete role mappings (realm and client roles)
200
 */
201
listRoleMappings(params: { id: string }): Promise<MappingsRepresentation>;
202

203
/**
204
 * Add realm roles to a group
205
 * @param params - Group identifier and roles to add
206
 */
207
addRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;
208

209
/**
210
 * List current realm role mappings for a group
211
 * @param params - Group identifier
212
 * @returns Array of assigned realm roles
213
 */
214
listRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
215

216
/**
217
 * Remove realm roles from a group
218
 * @param params - Group identifier and roles to remove
219
 */
220
delRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;
221

222
/**
223
 * List available realm roles that can be assigned to the group
224
 * @param params - Group identifier
225
 * @returns Array of available realm roles
226
 */
227
listAvailableRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
228

229
/**
230
 * List effective realm roles (including composite roles)
231
 * @param params - Group identifier
232
 * @returns Array of effective realm roles
233
 */
234
listCompositeRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
235

236
/**
237
 * Add client roles to a group
238
 * @param params - Group ID, client ID, and roles to add
239
 */
240
addClientRoleMappings(params: {
241
  id: string;
242
  clientUniqueId: string;
243
  roles: RoleMappingPayload[];
244
}): Promise<void>;
245

246
/**
247
 * List current client role mappings for a group
248
 * @param params - Group and client identifiers
249
 * @returns Array of assigned client roles
250
 */
251
listClientRoleMappings(params: {
252
  id: string;
253
  clientUniqueId: string;
254
}): Promise<RoleRepresentation[]>;
255
```
256

257
**Usage Examples:**
258

259
```typescript
260
// Get all role mappings for a group
261
const roleMappings = await kcAdminClient.groups.listRoleMappings({
262
  id: groupId,
263
});
264

265
console.log("Realm roles:", roleMappings.realmMappings?.map(r => r.name));
266
console.log("Client roles:", Object.keys(roleMappings.clientMappings || {}));
267

268
// Add realm roles to group
269
await kcAdminClient.groups.addRealmRoleMappings({
270
  id: groupId,
271
  roles: [
272
    { id: "role-id-1", name: "developer" },
273
    { id: "role-id-2", name: "user" },
274
  ],
275
});
276

277
// Add client roles to group
278
await kcAdminClient.groups.addClientRoleMappings({
279
  id: groupId,
280
  clientUniqueId: clientId,
281
  roles: [
282
    { id: "client-role-id", name: "app-admin" },
283
  ],
284
});
285

286
// Remove roles from group
287
await kcAdminClient.groups.delRealmRoleMappings({
288
  id: groupId,
289
  roles: [{ id: "role-id-1", name: "developer" }],
290
});
291
```
292

293
## Query Interfaces
294

295
```typescript { .api }
296
/**
297
 * Group search and pagination query parameters
298
 */
299
interface GroupQuery extends PaginatedQuery, SummarizedQuery {
300
  /** Search term for group name */
301
  search?: string;
302
  /** Exact match for search term */
303
  exact?: boolean;
304
  /** Additional query parameters */
305
  [key: string]: string | number | undefined | boolean;
306
}
307

308
/**
309
 * Subgroup query parameters
310
 */
311
interface SubGroupQuery extends PaginatedQuery, SummarizedQuery {
312
  /** Parent group ID */
313
  parentId: string;
314
  /** Search term for subgroup name */
315
  search?: string;
316
}
317

318
/**
319
 * Group count query parameters
320
 */
321
interface GroupCountQuery {
322
  /** Search term */
323
  search?: string;
324
  /** Count only top-level groups */
325
  top?: boolean;
326
}
327

328
/**
329
 * Pagination query parameters
330
 */
331
interface PaginatedQuery {
332
  /** Number of results to skip */
333
  first?: number;
334
  /** Maximum number of results to return */
335
  max?: number;
336
}
337

338
/**
339
 * Brief representation option
340
 */
341
interface SummarizedQuery {
342
  /** Return brief representation (fewer fields) */
343
  briefRepresentation?: boolean;
344
}
345

346
/**
347
 * Role mapping payload for assignments
348
 */
349
interface RoleMappingPayload {
350
  /** Role ID */
351
  id?: string;
352
  /** Role name */
353
  name?: string;
354
}
355

356
/**
357
 * Complete role mappings structure
358
 */
359
interface MappingsRepresentation {
360
  /** Realm role mappings */
361
  realmMappings?: RoleRepresentation[];
362
  /** Client role mappings by client ID */
363
  clientMappings?: Record<string, RoleRepresentation[]>;
364
}
365
```
366

367
## Types
368

369
```typescript { .api }
370
/**
371
 * Group representation with hierarchy and attributes
372
 */
373
interface GroupRepresentation {
374
  /** Group unique identifier */
375
  id?: string;
376
  /** Group name */
377
  name?: string;
378
  /** Full path in group hierarchy */
379
  path?: string;
380
  /** Custom attributes */
381
  attributes?: Record<string, string[]>;
382
  /** Assigned realm roles */
383
  realmRoles?: string[];
384
  /** Assigned client roles by client ID */
385
  clientRoles?: Record<string, string[]>;
386
  /** Child groups */
387
  subGroups?: GroupRepresentation[];
388
  /** Parent group ID */
389
  parentId?: string;
390
  /** Number of subgroups */
391
  subGroupCount?: number;
392
}
393
```