0
# User Management
1

2
The Users resource provides comprehensive functionality for managing user accounts, including CRUD operations, role mappings, group memberships, credentials, sessions, and security actions.
3

4
## Capabilities
5

6
### User CRUD Operations
7

8
Basic user lifecycle management including creation, retrieval, updates, and deletion.
9

10
```typescript { .api }
11
/**
12
 * User query interface for filtering and pagination
13
 */
14
interface UserQuery extends PaginationQuery, SearchQuery, UserBaseQuery {
15
  /** Exact match search instead of substring matching */
16
  exact?: boolean;
17
  /** Allow additional dynamic query parameters */
18
  [key: string]: string | number | undefined | boolean;
19
}
20

21
interface PaginationQuery {
22
  /** Starting index for pagination (0-based) */
23
  first?: number;
24
  /** Maximum number of results to return */
25
  max?: number;
26
}
27

28
interface SearchQuery {
29
  /** General search term across multiple user fields */
30
  search?: string;
31
}
32

33
interface UserBaseQuery {
34
  /** Filter by email address */
35
  email?: string;
36
  /** Filter by first name */
37
  firstName?: string;
38
  /** Filter by last name */
39
  lastName?: string;
40
  /** Filter by username */
41
  username?: string;
42
  /** Query string for advanced search */
43
  q?: string;
44
}
45

46
/**
47
 * Find users with optional filtering and pagination
48
 * @param query - Optional query parameters for filtering users
49
 * @returns Array of user representations
50
 */
51
find(query?: UserQuery): Promise<UserRepresentation[]>;
52

53
/**
54
 * Create a new user
55
 * @param user - User representation with user details
56
 * @returns Object containing the ID of the created user
57
 */
58
create(user: UserRepresentation): Promise<{ id: string }>;
59

60
/**
61
 * Get a single user by ID
62
 * @param params - Parameters including user ID and optional metadata flag
63
 * @returns User representation or undefined if not found
64
 */
65
findOne(params: { id: string; userProfileMetadata?: boolean }): Promise<UserRepresentation | undefined>;
66

67
/**
68
 * Update an existing user
69
 * @param query - Query containing user ID
70
 * @param user - Updated user representation
71
 */
72
update(query: { id: string }, user: UserRepresentation): Promise<void>;
73

74
/**
75
 * Delete a user
76
 * @param params - Parameters containing user ID
77
 */
78
del(params: { id: string }): Promise<void>;
79

80
/**
81
 * Count total number of users matching query
82
 * @param query - Optional query parameters for filtering
83
 * @returns Total count of matching users
84
 */
85
count(query?: UserBaseQuery & SearchQuery): Promise<number>;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
// Find all users with pagination
92
const users = await kcAdminClient.users.find({
93
  first: 0,
94
  max: 20,
95
});
96

97
// Search users by email domain
98
const companyUsers = await kcAdminClient.users.find({
99
  email: "@company.com",
100
  exact: false,
101
});
102

103
// Create a new user
104
const { id } = await kcAdminClient.users.create({
105
  username: "johndoe",
106
  email: "john.doe@example.com",
107
  firstName: "John",
108
  lastName: "Doe",
109
  enabled: true,
110
  emailVerified: false,
111
  attributes: {
112
    department: ["Engineering"],
113
    location: ["New York"],
114
  },
115
});
116

117
// Update user details
118
await kcAdminClient.users.update({ id }, {
119
  firstName: "Jonathan",
120
  emailVerified: true,
121
  attributes: {
122
    department: ["Engineering"],
123
    location: ["San Francisco"],
124
  },
125
});
126

127
// Get user with profile metadata
128
const user = await kcAdminClient.users.findOne({ 
129
  id, 
130
  userProfileMetadata: true 
131
});
132

133
// Count users
134
const totalUsers = await kcAdminClient.users.count();
135
const activeUsers = await kcAdminClient.users.count({ 
136
  search: "enabled:true" 
137
});
138
```
139

140
### User Representation
141

142
Complete TypeScript interface for user data structure.
143

144
```typescript { .api }
145
/**
146
 * Complete user representation with all available fields
147
 */
148
interface UserRepresentation {
149
  /** Unique user identifier */
150
  id?: string;
151
  /** Timestamp when user was created */
152
  createdTimestamp?: number;
153
  /** Unique username for authentication */
154
  username?: string;
155
  /** Whether the user account is enabled */
156
  enabled?: boolean;
157
  /** Whether user has TOTP configured */
158
  totp?: boolean;
159
  /** Whether user's email is verified */
160
  emailVerified?: boolean;
161
  /** Credential types that can be disabled for this user */
162
  disableableCredentialTypes?: string[];
163
  /** Required actions that must be completed */
164
  requiredActions?: (RequiredActionAlias | string)[];
165
  /** Not-before policy timestamp */
166
  notBefore?: number;
167
  /** Access control permissions */
168
  access?: Record<string, boolean>;
169

170
  // Optional profile fields
171
  /** Custom user attributes */
172
  attributes?: Record<string, any>;
173
  /** User consent information */
174
  clientConsents?: UserConsentRepresentation[];
175
  /** Client-specific role mappings */
176
  clientRoles?: Record<string, any>;
177
  /** User credentials */
178
  credentials?: CredentialRepresentation[];
179
  /** Email address */
180
  email?: string;
181
  /** Federated identity links */
182
  federatedIdentities?: FederatedIdentityRepresentation[];
183
  /** Federation link identifier */
184
  federationLink?: string;
185
  /** First name */
186
  firstName?: string;
187
  /** Group memberships */
188
  groups?: string[];
189
  /** Last name */
190
  lastName?: string;
191
  /** Realm-level role assignments */
192
  realmRoles?: string[];
193
  /** Self-reference URL */
194
  self?: string;
195
  /** Service account client ID (if user is a service account) */
196
  serviceAccountClientId?: string;
197
  /** User profile metadata */
198
  userProfileMetadata?: UserProfileMetadata;
199
}
200

201
/**
202
 * Required action types that can be assigned to users
203
 */
204
enum RequiredActionAlias {
205
  VERIFY_EMAIL = "VERIFY_EMAIL",
206
  UPDATE_PROFILE = "UPDATE_PROFILE", 
207
  CONFIGURE_TOTP = "CONFIGURE_TOTP",
208
  UPDATE_PASSWORD = "UPDATE_PASSWORD",
209
  TERMS_AND_CONDITIONS = "TERMS_AND_CONDITIONS",
210
}
211
```
212

213
### User Profile Management
214

215
User profile configuration and metadata management for advanced user schemas.
216

217
```typescript { .api }
218
/**
219
 * Get user profile configuration for the realm
220
 * @returns User profile configuration
221
 */
222
getProfile(): Promise<UserProfileConfig>;
223

224
/**
225
 * Update user profile configuration
226
 * @param profile - New profile configuration
227
 * @returns Updated profile configuration
228
 */
229
updateProfile(profile: UserProfileConfig): Promise<UserProfileConfig>;
230

231
/**
232
 * Get user profile metadata
233
 * @returns Profile metadata including attribute definitions
234
 */
235
getProfileMetadata(): Promise<UserProfileMetadata>;
236
```
237

238
### Role Mappings
239

240
Complete role mapping management for both realm and client roles.
241

242
```typescript { .api }
243
/**
244
 * List all role mappings for a user (realm and client roles)
245
 * @param params - Parameters containing user ID
246
 * @returns Complete role mappings representation
247
 */
248
listRoleMappings(params: { id: string }): Promise<MappingsRepresentation>;
249

250
/**
251
 * Add realm role mappings to user
252
 * @param params - User ID and roles to add
253
 */
254
addRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;
255

256
/**
257
 * List realm role mappings for user
258
 * @param params - Parameters containing user ID
259
 * @returns Array of realm roles assigned to user
260
 */
261
listRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
262

263
/**
264
 * Remove realm role mappings from user
265
 * @param params - User ID and roles to remove
266
 */
267
delRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;
268

269
/**
270
 * List available realm roles that can be assigned to user
271
 * @param params - Parameters containing user ID
272
 * @returns Array of available realm roles
273
 */
274
listAvailableRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
275

276
/**
277
 * List effective realm role mappings (including composite roles)
278
 * @param params - Parameters containing user ID
279
 * @returns Array of effective realm roles
280
 */
281
listCompositeRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
282
```
283

284
**Role Mapping Examples:**
285

286
```typescript
287
// Assign realm roles to user
288
await kcAdminClient.users.addRealmRoleMappings({
289
  id: userId,
290
  roles: [
291
    { id: "admin-role-id", name: "admin" },
292
    { id: "user-role-id", name: "user" },
293
  ],
294
});
295

296
// List user's current realm roles
297
const realmRoles = await kcAdminClient.users.listRealmRoleMappings({ id: userId });
298

299
// Remove specific realm role
300
await kcAdminClient.users.delRealmRoleMappings({
301
  id: userId,
302
  roles: [{ id: "user-role-id", name: "user" }],
303
});
304

305
// Check available roles for assignment
306
const availableRoles = await kcAdminClient.users.listAvailableRealmRoleMappings({ 
307
  id: userId 
308
});
309
```
310

311
### Client Role Mappings
312

313
Management of client-specific role assignments.
314

315
```typescript { .api }
316
/**
317
 * List client role mappings for user
318
 * @param params - User ID and client unique ID
319
 * @returns Array of client roles assigned to user
320
 */
321
listClientRoleMappings(params: { id: string; clientUniqueId: string }): Promise<RoleRepresentation[]>;
322

323
/**
324
 * Add client role mappings to user
325
 * @param params - User ID, client ID, and roles to add
326
 */
327
addClientRoleMappings(params: { id: string; clientUniqueId: string; roles: RoleMappingPayload[] }): Promise<void>;
328

329
/**
330
 * Remove client role mappings from user
331
 * @param params - User ID, client ID, and roles to remove
332
 */
333
delClientRoleMappings(params: { id: string; clientUniqueId: string; roles: RoleMappingPayload[] }): Promise<void>;
334

335
/**
336
 * List available client roles for assignment
337
 * @param params - User ID and client unique ID
338
 * @returns Array of available client roles
339
 */
340
listAvailableClientRoleMappings(params: { id: string; clientUniqueId: string }): Promise<RoleRepresentation[]>;
341

342
/**
343
 * List effective client role mappings (including composite roles)
344
 * @param params - User ID and client unique ID
345
 * @returns Array of effective client roles
346
 */
347
listCompositeClientRoleMappings(params: { id: string; clientUniqueId: string }): Promise<RoleRepresentation[]>;
348

349
/**
350
 * Role mapping payload interface for assignment operations
351
 */
352
interface RoleMappingPayload extends RoleRepresentation {
353
  /** Role ID (required for mapping operations) */
354
  id: string;
355
  /** Role name (required for mapping operations) */
356
  name: string;
357
}
358
```
359

360
**Client Role Examples:**
361

362
```typescript
363
// Assign client roles to user
364
await kcAdminClient.users.addClientRoleMappings({
365
  id: userId,
366
  clientUniqueId: "my-client-id",
367
  roles: [
368
    { id: "client-role-id", name: "client-admin" },
369
    { id: "another-role-id", name: "client-user" },
370
  ],
371
});
372

373
// List user's roles for specific client
374
const clientRoles = await kcAdminClient.users.listClientRoleMappings({
375
  id: userId,
376
  clientUniqueId: "my-client-id",
377
});
378
```
379

380
### Group Management
381

382
User group membership operations.
383

384
```typescript { .api }
385
/**
386
 * List groups that a user belongs to
387
 * @param params - User ID with optional pagination and search
388
 * @returns Array of groups the user is a member of
389
 */
390
listGroups(params: { 
391
  id: string; 
392
  briefRepresentation?: boolean; 
393
} & PaginationQuery & SearchQuery): Promise<GroupRepresentation[]>;
394

395
/**
396
 * Add user to a group
397
 * @param params - User ID and group ID
398
 * @returns Success message
399
 */
400
addToGroup(params: { id: string; groupId: string }): Promise<string>;
401

402
/**
403
 * Remove user from a group
404
 * @param params - User ID and group ID  
405
 * @returns Success message
406
 */
407
delFromGroup(params: { id: string; groupId: string }): Promise<string>;
408

409
/**
410
 * Count number of groups user belongs to
411
 * @param params - User ID with optional search
412
 * @returns Object containing the count
413
 */
414
countGroups(params: { id: string; search?: string }): Promise<{ count: number }>;
415
```
416

417
**Group Management Examples:**
418

419
```typescript
420
// Add user to group
421
await kcAdminClient.users.addToGroup({
422
  id: userId,
423
  groupId: "engineering-group-id",
424
});
425

426
// List user's groups
427
const userGroups = await kcAdminClient.users.listGroups({
428
  id: userId,
429
  briefRepresentation: true,
430
});
431

432
// Remove from group
433
await kcAdminClient.users.delFromGroup({
434
  id: userId, 
435
  groupId: "old-group-id",
436
});
437
```
438

439
### Credential Management
440

441
User credential and password management operations.
442

443
```typescript { .api }
444
/**
445
 * Reset user's password
446
 * @param params - User ID and new credential
447
 */
448
resetPassword(params: { id: string; credential: CredentialRepresentation }): Promise<void>;
449

450
/**
451
 * Remove TOTP configuration from user
452
 * @param params - Parameters containing user ID
453
 */
454
removeTotp(params: { id: string }): Promise<void>;
455

456
/**
457
 * Get user's configured credential types from user storage
458
 * @param params - Parameters containing user ID
459
 * @returns Array of credential type names
460
 */
461
getUserStorageCredentialTypes(params: { id: string }): Promise<string[]>;
462

463
/**
464
 * Get user's credentials
465
 * @param params - Parameters containing user ID
466
 * @returns Array of user credentials
467
 */
468
getCredentials(params: { id: string }): Promise<CredentialRepresentation[]>;
469

470
/**
471
 * Delete a specific credential
472
 * @param params - User ID and credential ID
473
 */
474
deleteCredential(params: { id: string; credentialId: string }): Promise<void>;
475

476
/**
477
 * Update credential label
478
 * @param query - User ID and credential ID
479
 * @param label - New label for the credential
480
 */
481
updateCredentialLabel(query: { id: string; credentialId: string }, label: string): Promise<void>;
482

483
/**
484
 * Move credential position down in the list
485
 * @param params - User ID, credential ID, and new previous credential ID
486
 */
487
moveCredentialPositionDown(params: {
488
  id: string;
489
  credentialId: string;
490
  newPreviousCredentialId: string;
491
}): Promise<void>;
492

493
/**
494
 * Move credential to first position
495
 * @param params - User ID and credential ID
496
 */
497
moveCredentialPositionUp(params: { id: string; credentialId: string }): Promise<void>;
498

499
/**
500
 * Credential representation for password and authentication data
501
 */
502
interface CredentialRepresentation {
503
  /** Creation timestamp */
504
  createdDate?: number;
505
  /** Encrypted credential data */
506
  credentialData?: string;
507
  /** Credential unique identifier */
508
  id?: string;
509
  /** Priority for credential ordering */
510
  priority?: number;
511
  /** Encrypted secret data */
512
  secretData?: string;
513
  /** Whether credential is temporary */
514
  temporary?: boolean;
515
  /** Type of credential (password, totp, etc.) */
516
  type?: string;
517
  /** User-defined label */
518
  userLabel?: string;
519
  /** Credential value (for temporary passwords) */
520
  value?: string;
521
  /** Federation link reference */
522
  federationLink?: string;
523
}
524
```
525

526
**Credential Management Examples:**
527

528
```typescript
529
// Reset user password
530
await kcAdminClient.users.resetPassword({
531
  id: userId,
532
  credential: {
533
    type: "password",
534
    value: "newSecurePassword123",
535
    temporary: false, // User won't need to change on first login
536
  },
537
});
538

539
// Set temporary password (user must change on next login)
540
await kcAdminClient.users.resetPassword({
541
  id: userId,
542
  credential: {
543
    type: "password",
544
    value: "temporaryPassword",
545
    temporary: true,
546
  },
547
});
548

549
// Get user credentials
550
const credentials = await kcAdminClient.users.getCredentials({ id: userId });
551

552
// Remove TOTP
553
await kcAdminClient.users.removeTotp({ id: userId });
554
```
555

556
### Email Actions
557

558
Send email notifications and verification requests to users.
559

560
```typescript { .api }
561
/**
562
 * Send action email to user with required actions to complete
563
 * @param params - User ID and email action configuration
564
 */
565
executeActionsEmail(params: {
566
  id: string;
567
  /** Client ID for redirect context */
568
  clientId?: string;
569
  /** Email link lifespan in seconds */
570
  lifespan?: number;
571
  /** Redirect URI after actions completion */
572
  redirectUri?: string;
573
  /** Required actions to include in email */
574
  actions?: (RequiredActionAlias | string)[];
575
}): Promise<void>;
576

577
/**
578
 * Send email verification to user
579
 * @param params - User ID with optional client context
580
 */
581
sendVerifyEmail(params: { 
582
  id: string; 
583
  clientId?: string; 
584
  redirectUri?: string; 
585
}): Promise<void>;
586
```
587

588
**Email Examples:**
589

590
```typescript
591
// Send password reset email
592
await kcAdminClient.users.executeActionsEmail({
593
  id: userId,
594
  clientId: "my-app",
595
  redirectUri: "https://myapp.com/auth/callback",
596
  lifespan: 3600, // 1 hour
597
  actions: ["UPDATE_PASSWORD"],
598
});
599

600
// Send profile update email
601
await kcAdminClient.users.executeActionsEmail({
602
  id: userId,
603
  actions: ["UPDATE_PROFILE", "VERIFY_EMAIL"],
604
});
605

606
// Send email verification
607
await kcAdminClient.users.sendVerifyEmail({
608
  id: userId,
609
  clientId: "my-app",
610
  redirectUri: "https://myapp.com/verified",
611
});
612
```
613

614
### Session Management
615

616
User session monitoring and management.
617

618
```typescript { .api }
619
/**
620
 * List active user sessions
621
 * @param params - Parameters containing user ID
622
 * @returns Array of active user sessions
623
 */
624
listSessions(params: { id: string }): Promise<UserSessionRepresentation[]>;
625

626
/**
627
 * List offline sessions for user and client
628
 * @param params - User ID and client ID
629
 * @returns Array of offline sessions
630
 */
631
listOfflineSessions(params: { id: string; clientId: string }): Promise<UserSessionRepresentation[]>;
632

633
/**
634
 * Logout user from all sessions
635
 * @param params - Parameters containing user ID
636
 */
637
logout(params: { id: string }): Promise<void>;
638
```
639

640
### Consent Management
641

642
User consent and application permissions management.
643

644
```typescript { .api }
645
/**
646
 * List user's granted consents
647
 * @param params - Parameters containing user ID
648
 * @returns Array of user consent representations
649
 */
650
listConsents(params: { id: string }): Promise<UserConsentRepresentation[]>;
651

652
/**
653
 * Revoke user consent for specific client
654
 * @param params - User ID and client ID
655
 */
656
revokeConsent(params: { id: string; clientId: string }): Promise<void>;
657
```
658

659
### Federated Identity
660

661
External identity provider link management.
662

663
```typescript { .api }
664
/**
665
 * List federated identities linked to user
666
 * @param params - Parameters containing user ID
667
 * @returns Array of federated identity links
668
 */
669
listFederatedIdentities(params: { id: string }): Promise<FederatedIdentityRepresentation[]>;
670

671
/**
672
 * Add federated identity link to user
673
 * @param params - User ID, provider ID, and federated identity details
674
 */
675
addToFederatedIdentity(params: {
676
  id: string;
677
  federatedIdentityId: string;
678
  federatedIdentity: FederatedIdentityRepresentation;
679
}): Promise<void>;
680

681
/**
682
 * Remove federated identity link from user
683
 * @param params - User ID and federated identity provider ID
684
 */
685
delFromFederatedIdentity(params: { id: string; federatedIdentityId: string }): Promise<void>;
686
```
687

688
### Advanced Operations
689

690
Additional user management operations for impersonation and attributes.
691

692
```typescript { .api }
693
/**
694
 * Impersonate a user (admin capability)
695
 * @param query - User ID to impersonate
696
 * @param payload - Impersonation context
697
 * @returns Impersonation result data
698
 */
699
impersonation(query: { id: string }, payload: { user: string; realm: string }): Promise<Record<string, any>>;
700

701
/**
702
 * Get unmanaged user attributes
703
 * @param params - Parameters containing user ID
704
 * @returns Record of attribute names to value arrays
705
 */
706
getUnmanagedAttributes(params: { id: string }): Promise<Record<string, string[]>>;
707
```