0
# Keycloak Admin Client
1

2
Keycloak Admin Client is a comprehensive TypeScript library that provides a type-safe API for interacting with Keycloak's Administration API. It enables developers to programmatically manage realms, users, groups, roles, clients, and authentication policies with full TypeScript support and automatic token management.
3

4
## Package Information
5

6
- **Package Name**: @keycloak/keycloak-admin-client
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @keycloak/keycloak-admin-client`
10

11
## Core Imports
12

13
```typescript
14
import KeycloakAdminClient from "@keycloak/keycloak-admin-client";
15
import { requiredAction, NetworkError } from "@keycloak/keycloak-admin-client";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const KeycloakAdminClient = require("@keycloak/keycloak-admin-client").default;
22
const { requiredAction, NetworkError } = require("@keycloak/keycloak-admin-client");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import KeycloakAdminClient from "@keycloak/keycloak-admin-client";
29

30
// Initialize client
31
const kcAdminClient = new KeycloakAdminClient({
32
  baseUrl: 'http://localhost:8080',
33
  realmName: 'master',
34
});
35

36
// Authenticate with password grant
37
await kcAdminClient.auth({
38
  username: 'admin',
39
  password: 'admin',
40
  grantType: 'password',
41
  clientId: 'admin-cli',
42
});
43

44
// Create a user
45
const { id } = await kcAdminClient.users.create({
46
  username: 'newuser',
47
  email: 'newuser@example.com',
48
  enabled: true,
49
});
50

51
// Find users
52
const users = await kcAdminClient.users.find({ max: 10 });
53

54
// Create a client
55
const client = await kcAdminClient.clients.create({
56
  clientId: 'my-client',
57
  enabled: true,
58
  publicClient: false,
59
});
60
```
61

62
## Architecture
63

64
Keycloak Admin Client is built around several key components:
65

66
- **KeycloakAdminClient Class**: Main client class that manages authentication and provides access to all resource endpoints
67
- **Resource Classes**: Specialized classes for each API area (Users, Clients, Realms, etc.) that handle HTTP operations
68
- **Authentication System**: Flexible authentication supporting multiple grant types and token providers
69
- **Type System**: Complete TypeScript definitions for all Keycloak entities and API parameters
70
- **Error Handling**: Custom NetworkError class with detailed response information
71
- **Agent Infrastructure**: Base HTTP client with automatic URL templating and query parameter handling
72

73
## Capabilities
74

75
### Client Configuration
76

77
Core client setup, authentication flows, and token management for connecting to Keycloak Admin API.
78

79
```typescript { .api }
80
class KeycloakAdminClient {
81
  // Resource properties
82
  users: Users;
83
  userStorageProvider: UserStorageProvider;
84
  groups: Groups;
85
  roles: Roles;
86
  organizations: Organizations;
87
  clients: Clients;
88
  realms: Realms;
89
  clientScopes: ClientScopes;
90
  clientPolicies: ClientPolicies;
91
  identityProviders: IdentityProviders;
92
  components: Components;
93
  serverInfo: ServerInfo;
94
  whoAmI: WhoAmI;
95
  attackDetection: AttackDetection;
96
  authenticationManagement: AuthenticationManagement;
97
  cache: Cache;
98

99
  constructor(connectionConfig?: ConnectionConfig);
100
  
101
  async auth(credentials: Credentials): Promise<void>;
102
  registerTokenProvider(provider: TokenProvider): void;
103
  setAccessToken(token: string): void;
104
  async getAccessToken(): Promise<string | undefined>;
105
  setConfig(connectionConfig: ConnectionConfig): void;
106
}
107

108
interface ConnectionConfig {
109
  baseUrl?: string;
110
  realmName?: string;
111
  requestOptions?: RequestInit;
112
  requestArgOptions?: Pick<RequestArgs, "catchNotFound">;
113
}
114
```
115

116
[Client Configuration](./client-configuration.md)
117

118
### User Management
119

120
Complete user lifecycle management including creation, updates, role assignments, group membership, credential management, and session handling.
121

122
```typescript { .api }
123
interface Users {
124
  find(query?: UserQuery): Promise<UserRepresentation[]>;
125
  create(user: UserRepresentation): Promise<{ id: string }>;
126
  findOne(params: { id: string; userProfileMetadata?: boolean }): Promise<UserRepresentation | undefined>;
127
  update(query: { id: string }, user: UserRepresentation): Promise<void>;
128
  del(params: { id: string }): Promise<void>;
129
  
130
  // Role mappings
131
  addRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;
132
  listRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;
133
  
134
  // Group management
135
  addToGroup(params: { id: string; groupId: string }): Promise<string>;
136
  listGroups(params: { id: string } & PaginationQuery): Promise<GroupRepresentation[]>;
137
}
138
```
139

140
[User Management](./user-management.md)
141

142
### Client Management
143

144
OAuth/OIDC client configuration, authorization services, client roles, protocol mappers, and client policy management.
145

146
```typescript { .api }
147
interface Clients {
148
  find(query?: ClientQuery): Promise<ClientRepresentation[]>;
149
  create(client: ClientRepresentation): Promise<{ id: string }>;
150
  findOne(params: { id: string }): Promise<ClientRepresentation | undefined>;
151
  update(query: { id: string }, client: ClientRepresentation): Promise<void>;
152
  del(params: { id: string }): Promise<void>;
153
  
154
  // Client roles
155
  createRole(params: { id: string }, role: RoleRepresentation): Promise<{ roleName: string }>;
156
  listRoles(params: { id: string }): Promise<RoleRepresentation[]>;
157
  
158
  // Authorization services
159
  listResources(params: { id: string }, query?: ResourceQuery): Promise<ResourceRepresentation[]>;
160
  createResource(params: { id: string }, resource: ResourceRepresentation): Promise<ResourceRepresentation>;
161
}
162
```
163

164
[Client Management](./client-management.md)
165

166
### Realm Management
167

168
Realm configuration, import/export, event management, default groups, and administrative settings.
169

170
```typescript { .api }
171
interface Realms {
172
  find(query?: { briefRepresentation?: boolean }): Promise<RealmRepresentation[]>;
173
  create(realm: RealmRepresentation): Promise<{ realmName: string }>;
174
  findOne(params: { realm: string }): Promise<RealmRepresentation | undefined>;
175
  update(query: { realm: string }, realm: RealmRepresentation): Promise<void>;
176
  del(params: { realm: string }): Promise<void>;
177
  
178
  // Import/Export
179
  partialImport(params: { realm: string; rep: PartialImportRealmRepresentation }): Promise<PartialImportResponse>;
180
  export(params: { realm: string; exportClients?: boolean; exportGroupsAndRoles?: boolean }): Promise<RealmRepresentation>;
181
}
182
```
183

184
[Realm Management](./realm-management.md)
185

186
### Group Management
187

188
Group hierarchy management, member administration, and group-based role assignments.
189

190
```typescript { .api }
191
interface Groups {
192
  find(query?: GroupQuery): Promise<GroupRepresentation[]>;
193
  create(group: GroupRepresentation): Promise<{ id: string }>;
194
  findOne(params: { id: string }): Promise<GroupRepresentation | undefined>;
195
  update(query: { id: string }, group: GroupRepresentation): Promise<void>;
196
  del(params: { id: string }): Promise<void>;
197
  
198
  // Group hierarchy
199
  listSubGroups(query: SubGroupQuery): Promise<GroupRepresentation[]>;
200
  setOrCreateChild(query: { id: string }, group: GroupRepresentation): Promise<{ id: string }>;
201
  listMembers(params: { id: string } & PaginatedQuery): Promise<UserRepresentation[]>;
202
}
203
```
204

205
[Group Management](./group-management.md)
206

207
### Role Management
208

209
Realm and client role management with composite role support and role mapping operations.
210

211
```typescript { .api }
212
interface Roles {
213
  find(query?: RoleQuery): Promise<RoleRepresentation[]>;
214
  create(role: RoleRepresentation): Promise<{ roleName: string }>;
215
  findByName(params: { name: string }): Promise<RoleRepresentation>;
216
  update(query: { name: string }, role: RoleRepresentation): Promise<void>;
217
  del(params: { name: string }): Promise<void>;
218
  
219
  // Composite roles
220
  getCompositeRoles(params: { name: string }): Promise<RoleRepresentation[]>;
221
  getCompositeRolesForRealm(params: { name: string }): Promise<RoleRepresentation[]>;
222
  getCompositeRolesForClient(params: { name: string; clientId: string }): Promise<RoleRepresentation[]>;
223
}
224
```
225

226
[Role Management](./role-management.md)
227

228
### Organization Management
229

230
Organization lifecycle management, member administration, and organizational identity provider configuration.
231

232
```typescript { .api }
233
interface Organizations {
234
  find(query?: OrganizationsQuery): Promise<OrganizationRepresentation[]>;
235
  create(organization: OrganizationRepresentation): Promise<OrganizationRepresentation>;
236
  findOne(params: { orgId: string }): Promise<OrganizationRepresentation | undefined>;
237
  update(params: { orgId: string }, organization: OrganizationRepresentation): Promise<void>;
238
  del(params: { orgId: string }): Promise<void>;
239
  
240
  // Members
241
  findMembers(params: { orgId: string }, query?: MembersQuery): Promise<UserRepresentation[]>;
242
  inviteUser(params: { orgId: string }, invitation: InvitationRequest): Promise<void>;
243
}
244
```
245

246
[Organization Management](./organization-management.md)
247

248
### Identity Providers
249

250
External identity provider configuration including SAML, OIDC, and social login integrations.
251

252
```typescript { .api }
253
interface IdentityProviders {
254
  find(): Promise<IdentityProviderRepresentation[]>;
255
  create(identityProvider: IdentityProviderRepresentation): Promise<void>;
256
  findOne(params: { alias: string }): Promise<IdentityProviderRepresentation | undefined>;
257
  update(params: { alias: string }, identityProvider: IdentityProviderRepresentation): Promise<void>;
258
  del(params: { alias: string }): Promise<void>;
259
  
260
  // Mappers
261
  findMappers(params: { alias: string }): Promise<IdentityProviderMapperRepresentation[]>;
262
  createMapper(params: { alias: string }, mapper: IdentityProviderMapperRepresentation): Promise<IdentityProviderMapperRepresentation>;
263
}
264
```
265

266
[Identity Providers](./identity-providers.md)
267

268
### Authentication Management
269

270
Authentication flow configuration, execution management, and authenticator configuration.
271

272
```typescript { .api }
273
interface AuthenticationManagement {
274
  getFlows(): Promise<AuthenticationFlowRepresentation[]>;
275
  createFlow(flow: AuthenticationFlowRepresentation): Promise<void>;
276
  getFlow(params: { flowId: string }): Promise<AuthenticationFlowRepresentation>;
277
  updateFlow(params: { flowId: string }, flow: AuthenticationFlowRepresentation): Promise<void>;
278
  deleteFlow(params: { flowId: string }): Promise<void>;
279
  
280
  // Executions
281
  getExecutions(params: { flowAlias: string }): Promise<AuthenticationExecutionInfoRepresentation[]>;
282
  addExecution(params: { flowAlias: string }, execution: AuthenticationExecutionRepresentation): Promise<void>;
283
}
284
```
285

286
[Authentication Management](./authentication-management.md)
287

288
### Client Scopes
289

290
Client scope management including protocol mappers, default scopes, and scope mappings for OpenID Connect and SAML protocols.
291

292
```typescript { .api }
293
interface ClientScopes {
294
  find(): Promise<ClientScopeRepresentation[]>;
295
  create(clientScope: ClientScopeRepresentation): Promise<{ id: string }>;
296
  findOne(params: { id: string }): Promise<ClientScopeRepresentation | undefined>;
297
  update(query: { id: string }, clientScope: ClientScopeRepresentation): Promise<void>;
298
  del(params: { id: string }): Promise<void>;
299
  
300
  // Protocol mappers
301
  addProtocolMapper(query: { id: string }, mapper: ProtocolMapperRepresentation): Promise<void>;
302
  listProtocolMappers(params: { id: string }): Promise<ProtocolMapperRepresentation[]>;
303
  
304
  // Default scopes
305
  listDefaultClientScopes(): Promise<ClientScopeRepresentation[]>;
306
  addDefaultClientScope(params: { id: string }): Promise<void>;
307
}
308
```
309

310
[Client Scopes](./client-scopes.md)
311

312
### Client Policies
313

314
Client policies and profiles for enforcing security policies and configuration standards across registered clients.
315

316
```typescript { .api }
317
interface ClientPolicies {
318
  listProfiles(params?: { includeGlobalProfiles?: boolean }): Promise<ClientProfilesRepresentation>;
319
  createProfiles(profiles: ClientProfilesRepresentation): Promise<void>;
320
  listPolicies(params?: { includeGlobalPolicies?: boolean }): Promise<ClientPoliciesRepresentation>;
321
  updatePolicy(policies: ClientPoliciesRepresentation): Promise<void>;
322
}
323
```
324

325
[Client Policies](./client-policies.md)
326

327
### Components
328

329
Keycloak component management for user storage providers, event listeners, and other pluggable system extensions.
330

331
```typescript { .api }
332
interface Components {
333
  find(query?: ComponentQuery): Promise<ComponentRepresentation[]>;
334
  create(component: ComponentRepresentation): Promise<{ id: string }>;
335
  findOne(params: { id: string }): Promise<ComponentRepresentation | undefined>;
336
  update(query: { id: string }, component: ComponentRepresentation): Promise<void>;
337
  del(params: { id: string }): Promise<void>;
338
  listSubComponents(params: { id: string; type: string }): Promise<ComponentTypeRepresentation[]>;
339
}
340
```
341

342
[Components](./components.md)
343

344
### Server Info
345

346
Server information and configuration details including version, providers, themes, and message bundles.
347

348
```typescript { .api }
349
interface ServerInfo {
350
  find(): Promise<ServerInfoRepresentation>;
351
  findEffectiveMessageBundles(query: MessageBundleQuery): Promise<EffectiveMessageBundleRepresentation[]>;
352
}
353
```
354

355
[Server Info](./server-info.md)
356

357
### WhoAmI
358

359
Current admin user context and permissions information within the Keycloak admin console.
360

361
```typescript { .api }
362
interface WhoAmI {
363
  find(params: { currentRealm: string }): Promise<WhoAmIRepresentation>;
364
}
365
```
366

367
[WhoAmI](./whoami.md)
368

369
### Attack Detection
370

371
Brute force protection management for monitoring and clearing attack detection data.
372

373
```typescript { .api }
374
interface AttackDetection {
375
  findOne(params: { id: string }): Promise<Record<string, any> | undefined>;
376
  del(params: { id: string }): Promise<void>;
377
  delAll(): Promise<void>;
378
}
379
```
380

381
[Attack Detection](./attack-detection.md)
382

383
### Cache Management
384

385
Cache clearing operations for refreshing various Keycloak system caches.
386

387
```typescript { .api }
388
interface Cache {
389
  clearUserCache(): Promise<void>;
390
  clearKeysCache(): Promise<void>;
391
  clearCrlCache(): Promise<void>;
392
  clearRealmCache(): Promise<void>;
393
}
394
```
395

396
[Cache Management](./cache-management.md)
397

398
### User Storage Provider
399

400
Management of external user storage systems including synchronization and user federation operations.
401

402
```typescript { .api }
403
interface UserStorageProvider {
404
  name(params: { id: string }): Promise<NameResponse>;
405
  removeImportedUsers(params: { id: string }): Promise<void>;
406
  sync(params: { id: string; action?: ActionType }): Promise<SynchronizationResultRepresentation>;
407
  unlinkUsers(params: { id: string }): Promise<void>;
408
  mappersSync(params: { id: string; parentId: string; direction?: DirectionType }): Promise<SynchronizationResultRepresentation>;
409
}
410
```
411

412
[User Storage Provider](./user-storage-provider.md)
413

414
### Utility Functions
415

416
Error handling, network utilities, authentication helpers, and common constants for robust client operations.
417

418
```typescript { .api }
419
class NetworkError extends Error {
420
  response: Response;
421
  responseData: unknown;
422
  constructor(message: string, options: NetworkErrorOptions);
423
}
424

425
function fetchWithError(
426
  input: Request | string | URL,
427
  init?: RequestInit,
428
): Promise<Response>;
429

430
const requiredAction: typeof RequiredActionAlias;
431

432
enum RequiredActionAlias {
433
  VERIFY_EMAIL = "VERIFY_EMAIL",
434
  UPDATE_PROFILE = "UPDATE_PROFILE",
435
  CONFIGURE_TOTP = "CONFIGURE_TOTP",
436
  UPDATE_PASSWORD = "UPDATE_PASSWORD",
437
  TERMS_AND_CONDITIONS = "TERMS_AND_CONDITIONS",
438
}
439
```
440

441
[Utility Functions](./utility-functions.md)
442

443
## Core Types
444

445
```typescript { .api }
446
interface UserRepresentation {
447
  id?: string;
448
  username?: string;
449
  email?: string;
450
  firstName?: string;
451
  lastName?: string;
452
  enabled?: boolean;
453
  emailVerified?: boolean;
454
  attributes?: Record<string, string[]>;
455
  groups?: string[];
456
  roles?: string[];
457
  credentials?: CredentialRepresentation[];
458
}
459

460
interface ClientRepresentation {
461
  id?: string;
462
  clientId?: string;
463
  name?: string;
464
  description?: string;
465
  enabled?: boolean;
466
  publicClient?: boolean;
467
  protocol?: string;
468
  attributes?: Record<string, string>;
469
  redirectUris?: string[];
470
  webOrigins?: string[];
471
  defaultRoles?: string[];
472
}
473

474
interface RealmRepresentation {
475
  id?: string;
476
  realm?: string;
477
  displayName?: string;
478
  enabled?: boolean;
479
  sslRequired?: string;
480
  registrationAllowed?: boolean;
481
  loginWithEmailAllowed?: boolean;
482
  duplicateEmailsAllowed?: boolean;
483
  resetPasswordAllowed?: boolean;
484
  editUsernameAllowed?: boolean;
485
  bruteForceProtected?: boolean;
486
}
487

488
interface RoleRepresentation {
489
  id?: string;
490
  name?: string;
491
  description?: string;
492
  scopeParamRequired?: boolean;
493
  composite?: boolean;
494
  composites?: {
495
    realm?: string[];
496
    client?: Record<string, string[]>;
497
  };
498
  clientRole?: boolean;
499
  containerId?: string;
500
  attributes?: Record<string, string[]>;
501
}
502

503
interface GroupRepresentation {
504
  id?: string;
505
  name?: string;
506
  path?: string;
507
  attributes?: Record<string, string[]>;
508
  realmRoles?: string[];
509
  clientRoles?: Record<string, string[]>;
510
  subGroups?: GroupRepresentation[];
511
}
512
```