0
# Organization Management
1

2
Organization lifecycle management, member administration, and organizational identity provider configuration.
3

4
## Capabilities
5

6
### Organization CRUD Operations
7

8
Basic organization lifecycle management for multi-tenant scenarios.
9

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

18
/**
19
 * Create a new organization
20
 * @param organization - Organization configuration
21
 * @returns Created organization representation
22
 */
23
create(organization: OrganizationRepresentation): Promise<OrganizationRepresentation>;
24

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

32
/**
33
 * Update an existing organization
34
 * @param params - Organization identifier
35
 * @param organization - Updated organization configuration
36
 */
37
update(params: { orgId: string }, organization: OrganizationRepresentation): Promise<void>;
38

39
/**
40
 * Delete an organization
41
 * @param params - Organization identifier
42
 */
43
del(params: { orgId: string }): Promise<void>;
44
```
45

46
**Usage Examples:**
47

48
```typescript
49
// List all organizations
50
const orgs = await kcAdminClient.organizations.find();
51
console.log("Organizations:", orgs.map(o => o.name));
52

53
// Search organizations with pagination
54
const searchResults = await kcAdminClient.organizations.find({
55
  search: "acme",
56
  first: 0,
57
  max: 10,
58
});
59

60
// Create new organization
61
const newOrg = await kcAdminClient.organizations.create({
62
  name: "Acme Corporation",
63
  displayName: "Acme Corp",
64
  description: "Leading provider of innovative solutions",
65
  enabled: true,
66
  attributes: {
67
    industry: ["technology"],
68
    region: ["north-america"],
69
    size: ["enterprise"],
70
  },
71
});
72

73
console.log("Created organization:", newOrg.id);
74

75
// Get specific organization
76
const org = await kcAdminClient.organizations.findOne({
77
  orgId: newOrg.id!,
78
});
79

80
// Update organization
81
await kcAdminClient.organizations.update(
82
  { orgId: newOrg.id! },
83
  {
84
    displayName: "Acme Corporation Ltd",
85
    description: "Updated: Leading provider of innovative solutions",
86
    attributes: {
87
      industry: ["technology", "consulting"],
88
      region: ["north-america", "europe"],
89
      size: ["enterprise"],
90
    },
91
  }
92
);
93

94
// Delete organization
95
await kcAdminClient.organizations.del({ orgId: "org-to-delete" });
96
```
97

98
### Organization Members
99

100
Management of organization membership and user associations.
101

102
```typescript { .api }
103
/**
104
 * Find members of an organization
105
 * @param params - Organization identifier
106
 * @param query - Optional search and pagination parameters
107
 * @returns Array of organization members
108
 */
109
findMembers(params: { orgId: string }, query?: MembersQuery): Promise<UserRepresentation[]>;
110

111
/**
112
 * Invite user to organization
113
 * @param params - Organization identifier
114
 * @param invitation - Invitation details
115
 */
116
inviteUser(params: { orgId: string }, invitation: InvitationRequest): Promise<void>;
117

118
/**
119
 * Add existing user to organization
120
 * @param params - Organization and user identifiers
121
 */
122
addMember(params: { orgId: string; userId: string }): Promise<void>;
123

124
/**
125
 * Remove user from organization
126
 * @param params - Organization and user identifiers
127
 */
128
removeMember(params: { orgId: string; userId: string }): Promise<void>;
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
// Get all organization members
135
const members = await kcAdminClient.organizations.findMembers({
136
  orgId: organizationId,
137
});
138

139
console.log("Organization members:", members.map(u => u.username));
140

141
// Search members with pagination
142
const memberPage = await kcAdminClient.organizations.findMembers(
143
  { orgId: organizationId },
144
  {
145
    search: "john",
146
    first: 0,
147
    max: 20,
148
  }
149
);
150

151
// Invite user by email
152
await kcAdminClient.organizations.inviteUser(
153
  { orgId: organizationId },
154
  {
155
    email: "newuser@example.com",
156
    firstName: "John",
157
    lastName: "Doe",
158
    roles: ["member"],
159
    redirectUri: "https://myapp.com/welcome",
160
  }
161
);
162

163
// Add existing user to organization
164
const existingUser = await kcAdminClient.users.find({
165
  username: "existing-user",
166
}).then(users => users[0]);
167

168
await kcAdminClient.organizations.addMember({
169
  orgId: organizationId,
170
  userId: existingUser.id!,
171
});
172

173
// Remove member from organization
174
await kcAdminClient.organizations.removeMember({
175
  orgId: organizationId,
176
  userId: existingUser.id!,
177
});
178
```
179

180
### Organization Identity Providers
181

182
Configuration of identity providers specific to organizations.
183

184
```typescript { .api }
185
/**
186
 * List identity providers for an organization
187
 * @param params - Organization identifier
188
 * @returns Array of organization identity providers
189
 */
190
listIdentityProviders(params: { orgId: string }): Promise<OrganizationIdentityProviderRepresentation[]>;
191

192
/**
193
 * Add identity provider to organization
194
 * @param params - Organization identifier
195
 * @param provider - Identity provider configuration
196
 */
197
addIdentityProvider(params: {
198
  orgId: string;
199
}, provider: OrganizationIdentityProviderRepresentation): Promise<void>;
200

201
/**
202
 * Update organization identity provider
203
 * @param params - Organization and provider identifiers
204
 * @param provider - Updated provider configuration
205
 */
206
updateIdentityProvider(params: {
207
  orgId: string;
208
  alias: string;
209
}, provider: OrganizationIdentityProviderRepresentation): Promise<void>;
210

211
/**
212
 * Remove identity provider from organization
213
 * @param params - Organization and provider identifiers
214
 */
215
removeIdentityProvider(params: {
216
  orgId: string;
217
  alias: string;
218
}): Promise<void>;
219
```
220

221
**Usage Examples:**
222

223
```typescript
224
// List organization identity providers
225
const orgIdPs = await kcAdminClient.organizations.listIdentityProviders({
226
  orgId: organizationId,
227
});
228

229
console.log("Organization IdPs:", orgIdPs.map(idp => idp.alias));
230

231
// Add SAML identity provider to organization
232
await kcAdminClient.organizations.addIdentityProvider(
233
  { orgId: organizationId },
234
  {
235
    alias: "org-saml",
236
    providerId: "saml",
237
    enabled: true,
238
    config: {
239
      singleSignOnServiceUrl: "https://org.example.com/saml/sso",
240
      singleLogoutServiceUrl: "https://org.example.com/saml/slo",
241
      nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
242
    },
243
  }
244
);
245

246
// Update identity provider
247
await kcAdminClient.organizations.updateIdentityProvider(
248
  { orgId: organizationId, alias: "org-saml" },
249
  {
250
    enabled: false, // Temporarily disable
251
    config: {
252
      singleSignOnServiceUrl: "https://new-org.example.com/saml/sso",
253
    },
254
  }
255
);
256

257
// Remove identity provider
258
await kcAdminClient.organizations.removeIdentityProvider({
259
  orgId: organizationId,
260
  alias: "org-saml",
261
});
262
```
263

264
## Query Interfaces
265

266
```typescript { .api }
267
/**
268
 * Organization search and pagination query parameters
269
 */
270
interface OrganizationsQuery {
271
  /** Search term for organization name */
272
  search?: string;
273
  /** Exact match for search term */
274
  exact?: boolean;
275
  /** Number of results to skip */
276
  first?: number;
277
  /** Maximum number of results to return */
278
  max?: number;
279
}
280

281
/**
282
 * Organization members query parameters
283
 */
284
interface MembersQuery {
285
  /** Search term for member username/email */
286
  search?: string;
287
  /** Exact match for search term */
288
  exact?: boolean;
289
  /** Number of results to skip */
290
  first?: number;
291
  /** Maximum number of results to return */
292
  max?: number;
293
}
294

295
/**
296
 * User invitation request
297
 */
298
interface InvitationRequest {
299
  /** User email address */
300
  email: string;
301
  /** User first name */
302
  firstName?: string;
303
  /** User last name */
304
  lastName?: string;
305
  /** Organization roles to assign */
306
  roles?: string[];
307
  /** Redirect URI after acceptance */
308
  redirectUri?: string;
309
  /** Invitation expiration time in seconds */
310
  expirationTime?: number;
311
  /** Custom invitation message */
312
  message?: string;
313
}
314
```
315

316
## Types
317

318
```typescript { .api }
319
/**
320
 * Organization representation
321
 */
322
interface OrganizationRepresentation {
323
  /** Organization unique identifier */
324
  id?: string;
325
  /** Organization name (must be unique) */
326
  name?: string;
327
  /** Display name */
328
  displayName?: string;
329
  /** Organization description */
330
  description?: string;
331
  /** Whether organization is enabled */
332
  enabled?: boolean;
333
  /** Custom organization attributes */
334
  attributes?: Record<string, string[]>;
335
  /** Organization domains */
336
  domains?: OrganizationDomainRepresentation[];
337
  /** Organization members */
338
  members?: UserRepresentation[];
339
  /** Identity providers */
340
  identityProviders?: OrganizationIdentityProviderRepresentation[];
341
}
342

343
/**
344
 * Organization domain configuration
345
 */
346
interface OrganizationDomainRepresentation {
347
  /** Domain name */
348
  name?: string;
349
  /** Whether domain is verified */
350
  verified?: boolean;
351
}
352

353
/**
354
 * Organization-specific identity provider
355
 */
356
interface OrganizationIdentityProviderRepresentation {
357
  /** Identity provider alias */
358
  alias?: string;
359
  /** Provider type (saml, oidc, etc.) */
360
  providerId?: string;
361
  /** Whether provider is enabled */
362
  enabled?: boolean;
363
  /** Provider configuration */
364
  config?: Record<string, string>;
365
}
366
```
367

368
## Organization Management Patterns
369

370
Common patterns for organization management:
371

372
```typescript
373
// Pattern 1: Multi-tenant organization setup
374
const organizations = [
375
  { name: "acme-corp", displayName: "Acme Corporation" },
376
  { name: "beta-inc", displayName: "Beta Inc" },
377
  { name: "gamma-ltd", displayName: "Gamma Ltd" },
378
];
379

380
for (const orgData of organizations) {
381
  const org = await kcAdminClient.organizations.create({
382
    ...orgData,
383
    enabled: true,
384
    attributes: {
385
      tier: ["premium"],
386
      region: ["us-east"],
387
    },
388
  });
389
  
390
  // Set up organization-specific identity provider
391
  await kcAdminClient.organizations.addIdentityProvider(
392
    { orgId: org.id! },
393
    {
394
      alias: `${orgData.name}-saml`,
395
      providerId: "saml",
396
      enabled: true,
397
      config: {
398
        singleSignOnServiceUrl: `https://${orgData.name}.example.com/saml/sso`,
399
      },
400
    }
401
  );
402
}
403

404
// Pattern 2: Bulk user invitation
405
const invitations = [
406
  { email: "admin@acme.com", roles: ["admin", "member"] },
407
  { email: "user1@acme.com", roles: ["member"] },
408
  { email: "user2@acme.com", roles: ["member"] },
409
];
410

411
for (const invitation of invitations) {
412
  await kcAdminClient.organizations.inviteUser(
413
    { orgId: organizationId },
414
    {
415
      ...invitation,
416
      redirectUri: "https://myapp.com/org-welcome",
417
      expirationTime: 86400 * 7, // 7 days
418
    }
419
  );
420
}
421

422
// Pattern 3: Organization member management
423
const orgMembers = await kcAdminClient.organizations.findMembers({
424
  orgId: organizationId,
425
});
426

427
// Find inactive members and send reminder
428
const inactiveMembers = orgMembers.filter(member => {
429
  // Logic to determine inactive members
430
  return member.attributes?.lastLogin?.[0] < thirtyDaysAgo;
431
});
432

433
for (const member of inactiveMembers) {
434
  // Send reactivation email or remove from organization
435
  console.log(`Member ${member.username} has been inactive`);
436
}
437
```