keycloak-api-manager 6.0.1 → 6.0.3

package/docs/api/authentication-management.md

@@ -2,144 +2,417 @@
 
 Manage required actions, authentication flows, executions, and execution configs.
 
-**Namespace:** `KeycloakManager.authenticationManagement`
+Namespace: KeycloakManager.authenticationManagement
 
-## 1) Required Actions
+## Overview
+
+This handler controls Keycloak authentication internals at realm level:
+
+- Required actions lifecycle and config.
+- Flow creation/copy/read/update/delete.
+- Execution management inside flows.
+- Execution configuration metadata and values.
+- Provider discovery for authenticators and forms.
+
+All methods use the currently configured realm, unless an explicit realm override is supported by upstream endpoint payloads.
+
+## Required Actions
 
 ### getRequiredActions()
-- **Returns**: Promise<Array<object>>
+
+List registered required actions in realm.
+
+Returns:
+
+- Promise<Array<object>>
 
 ### getUnregisteredRequiredActions()
-- **Returns**: Promise<Array<object>>
+
+List available required actions not yet registered in realm.
+
+Returns:
+
+- Promise<Array<object>>
 
 ### registerRequiredAction(actionRepresentation)
-- **Required**: `alias`, `name`, `providerId`
-- **Optional**: `defaultAction`, `enabled`, `priority`, `config`
-- **Returns**: Promise<void>
+
+Register a required action.
+
+Parameters:
+
+- actionRepresentation (object, required)
+- alias (string, required)
+- name (string, required)
+- providerId (string, required)
+- defaultAction (boolean, optional)
+- enabled (boolean, optional)
+- priority (number, optional)
+- config (object, optional)
+
+Returns:
+
+- Promise<void>
 
 ### getRequiredActionForAlias(filter)
-- **Required**: `filter.alias`
-- **Returns**: Promise<object>
+
+Read one required action by alias.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+
+Returns:
+
+- Promise<object>
 
 ### updateRequiredAction(filter, actionRepresentation)
-- **Required**: `filter.alias`
-- **Required**: updated representation
-- **Returns**: Promise<void>
+
+Update one required action.
+
+Parameters:
+
+- filter (object, required):
+- alias (string, required)
+- actionRepresentation (object, required): updated action definition.
+
+Returns:
+
+- Promise<void>
 
 ### deleteRequiredAction(filter)
-- **Required**: `filter.alias`
-- **Returns**: Promise<void>
+
+Delete one required action by alias.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+
+Returns:
+
+- Promise<void>
 
 ### raiseRequiredActionPriority(filter)
 ### lowerRequiredActionPriority(filter)
-- **Required**: `filter.alias`
-- **Returns**: Promise<void>
+
+Move required action priority up or down.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+
+Returns:
+
+- Promise<void>
 
 ### getRequiredActionConfigDescription(filter)
-- **Required**: `filter.alias`
-- **Returns**: Promise<object>
+
+Get config schema/metadata for one required action.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+
+Returns:
+
+- Promise<object>
 
 ### getRequiredActionConfig(filter)
-- **Required**: `filter.alias`
-- **Returns**: Promise<object>
+
+Get current config values for one required action.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+
+Returns:
+
+- Promise<object>
 
 ### updateRequiredActionConfig(filter, actionConfigRepresentation)
-- **Required**: `filter.alias`
-- **Required**: config representation
-- **Returns**: Promise<void>
+
+Update config values for one required action.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+- actionConfigRepresentation (object, required)
+
+Returns:
+
+- Promise<void>
 
 ### removeRequiredActionConfig(filter)
-- **Required**: `filter.alias`
-- **Returns**: Promise<void>
 
-## 2) Authenticator / Provider Discovery
+Delete config for one required action.
+
+Parameters:
+
+- filter (object, required)
+- alias (string, required)
+
+Returns:
+
+- Promise<void>
+
+## Provider Discovery
 
 ### getClientAuthenticatorProviders()
 ### getFormActionProviders()
 ### getAuthenticatorProviders()
 ### getFormProviders()
-- **Params**: none
-- **Returns**: Promise<Array<object>>
 
-## 3) Authentication Flows
+List available provider metadata for the requested category.
+
+Parameters:
+
+- none
+
+Returns:
+
+- Promise<Array<object>>
+
+## Authentication Flows
 
 ### getFlows()
-- **Returns**: Promise<Array<object>>
+
+List authentication flows.
+
+Returns:
+
+- Promise<Array<object>>
 
 ### createFlow(flowRepresentation)
-- **Required**: `alias`, `providerId`, `topLevel`, `builtIn`
-- **Optional**: `description`
-- **Returns**: Promise<void>
+
+Create flow.
+
+Parameters:
+
+- flowRepresentation (object, required)
+- alias (string, required)
+- providerId (string, required), example basic-flow
+- topLevel (boolean, required)
+- builtIn (boolean, required)
+- description (string, optional)
+
+Returns:
+
+- Promise<void>
 
 ### updateFlow(filter, flowRepresentation)
-- **Required**: `filter.id` or `filter.alias` (as expected by endpoint)
-- **Required**: representation
-- **Returns**: Promise<void>
+
+Update existing flow.
+
+Parameters:
+
+- filter (object, required):
+- flowId (string, required): flow id used by endpoint.
+- flowRepresentation (object, required)
+
+Returns:
+
+- Promise<void>
 
 ### deleteFlow(filter)
-- **Required**: flow identifier (`id` or `alias`, per endpoint)
-- **Returns**: Promise<void>
+
+Delete flow.
+
+Parameters:
+
+- filter (object, required)
+- flowId (string, required): flow alias/id used by endpoint.
+
+Returns:
+
+- Promise<void>
 
 ### copyFlow(filter)
-- **Required**: source flow id/alias
-- **Required**: `filter.newName`
-- **Returns**: Promise<void>
+
+Copy existing flow.
+
+Parameters:
+
+- filter (object, required)
+- flow (string, required): source flow alias.
+- newName (string, required): alias for the copied flow.
+
+Returns:
+
+- Promise<void>
 
 ### getFlow(filter)
-- **Required**: flow identifier
-- **Returns**: Promise<object>
 
-## 4) Flow Executions
+Read one flow.
+
+Parameters:
+
+- filter (object, required)
+- flowId (string, required)
+
+Returns:
+
+- Promise<object>
+
+## Flow Executions
 
 ### getExecutions(filter)
-- **Required**: `filter.flowAlias`
-- **Returns**: Promise<Array<object>>
+
+List executions of a flow.
+
+Parameters:
+
+- filter (object, required)
+- flow (string, required): flow alias.
+
+Returns:
+
+- Promise<Array<object>>
 
 ### addExecutionToFlow(filter)
-- **Required**: `filter.flowAlias`
-- **Required**: `filter.provider`
-- **Returns**: Promise<void>
+
+Add execution to a flow.
+
+Parameters:
+
+- filter (object, required)
+- flow (string, required): flow alias.
+- provider (string, required): provider id to add.
+
+Returns:
+
+- Promise<void>
 
 ### addFlowToFlow(filter)
-- **Required**: `filter.flowAlias`
-- **Required**: nested flow payload
-- **Returns**: Promise<void>
+
+Add sub-flow to a parent flow.
+
+Parameters:
+
+- filter (object, required)
+- flow (string, required): parent flow alias.
+- alias (string, required): sub-flow alias.
+- type (string, required): flow type.
+- provider (string, required): provider id.
+- description (string, optional)
+
+Returns:
+
+- Promise<void>
 
 ### updateExecution(filter, executionRepresentation)
-- **Required**: execution reference fields
-- **Required**: execution representation
-- **Returns**: Promise<void>
+
+Update execution settings.
+
+Parameters:
+
+- filter (object, optional): realm-level routing context.
+- executionRepresentation (object, required): execution payload including id and fields like requirement/priority.
+
+Returns:
+
+- Promise<void>
 
 ### delExecution(filter)
-- **Required**: execution id reference
-- **Returns**: Promise<void>
+
+Delete execution.
+
+Parameters:
+
+- filter (object, required)
+- id (string, required): execution id.
+
+Returns:
+
+- Promise<void>
 
 ### raisePriorityExecution(filter)
 ### lowerPriorityExecution(filter)
-- **Required**: execution reference fields
-- **Returns**: Promise<void>
 
-## 5) Execution Config
+Change execution order.
+
+Parameters:
+
+- filter (object, required)
+- id (string, required): execution id.
+
+Returns:
+
+- Promise<void>
+
+## Execution Config
 
 ### createConfig(filter)
-- **Required**: execution reference + config payload
-- **Returns**: Promise<object>
+
+Create execution config.
+
+Parameters:
+
+- filter (object, required)
+- id (string, required): execution id.
+- alias (string, required): config alias.
+- config (object, optional): key/value map.
+
+Returns:
+
+- Promise<object>
 
 ### getConfig(filter)
-- **Required**: `filter.id` (config id)
-- **Returns**: Promise<object>
+
+Read one config by id.
+
+Parameters:
+
+- filter (object, required)
+- id (string, required): config id.
+
+Returns:
+
+- Promise<object>
 
 ### updateConfig(filter)
-- **Required**: config id + updated payload
-- **Returns**: Promise<void>
+
+Update one config.
+
+Parameters:
+
+- filter (object, required)
+- id (string, required): config id.
+- config (object, required): key/value map.
+
+Returns:
+
+- Promise<void>
 
 ### delConfig(filter)
-- **Required**: `filter.id` (config id)
-- **Returns**: Promise<void>
+
+Delete one config.
+
+Parameters:
+
+- filter (object, required)
+- id (string, required): config id.
+
+Returns:
+
+- Promise<void>
 
 ### getConfigDescription(filter)
-- **Required**: provider id / execution reference as required by endpoint
-- **Returns**: Promise<object>
+
+Get config schema description for a provider.
+
+Parameters:
+
+- filter (object, required)
+- providerId (string, required)
+
+Returns:
+
+- Promise<object>
 
 ## Example
 
@@ -153,6 +426,19 @@ await KeycloakManager.authenticationManagement.createFlow({
   topLevel: true,
   builtIn: false
 });
+
+await KeycloakManager.authenticationManagement.copyFlow({
+  flow: customFlowAlias,
+  newName: copiedFlowAlias,
+});
+
+const executions = await KeycloakManager.authenticationManagement.getExecutions({
+  flow: copiedFlowAlias,
+});
+
+if (executions[0]?.id) {
+  await KeycloakManager.authenticationManagement.raisePriorityExecution({ id: executions[0].id });
+}
 ```
 
 ## See Also

package/docs/api/client-policies.md

@@ -2,36 +2,102 @@
 
 Manage Client Policies and Client Profiles.
 
-**Namespace:** `KeycloakManager.clientPolicies`  
-**Required Feature Flag:** `client-policies`
+Namespace: KeycloakManager.clientPolicies
+
+Required Feature Flag: client-policies
+
+## Overview
+
+Client Policies let you enforce security requirements on clients (for example PKCE, redirect URI rules, access type restrictions).
+Client Profiles define reusable executor configurations that policies can reference.
+
+This handler exposes both read and update operations.
+
+Note: update endpoints are called through direct REST requests for compatibility across admin-client versions.
 
 ## Methods
 
 ### getPolicies(filter)
-Get current client policies configuration.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Get current client-policies configuration.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: configuration payload with policies and global settings.
 
 ### updatePolicies(filter, policiesRepresentation)
-Update client policies.
 
-- **Optional**: realm context fields
-- **Required**: `policiesRepresentation` (full/partial policies object)
-- **Returns**: Promise<void|object>
+Update client policies configuration.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+- policiesRepresentation (object, required): payload to persist.
+
+Typical fields in policiesRepresentation:
+
+- policies (array): list of policy definitions.
+- globalPolicies (array, optional): global policy names.
+
+Typical fields per policy item:
+
+- name (string, required): policy identifier.
+- description (string, optional): human-readable description.
+- enabled (boolean, optional): active/inactive state.
+- conditions (array, optional): list of match conditions.
+- profiles (array, optional): profile names applied when conditions match.
+
+Returns:
+
+- Promise<void|object>: usually no content (204), or response payload if provided by server.
 
 ### getProfiles(filter)
-Get current client profiles configuration.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Get current client-profiles configuration.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: configuration payload with profiles.
 
 ### updateProfiles(filter, profilesRepresentation)
-Update client profiles.
 
-- **Optional**: realm context fields
-- **Required**: `profilesRepresentation`
-- **Returns**: Promise<void|object>
+Update client profiles configuration.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+- profilesRepresentation (object, required): payload to persist.
+
+Typical fields in profilesRepresentation:
+
+- profiles (array): list of profile definitions.
+
+Typical fields per profile item:
+
+- name (string, required): profile identifier.
+- description (string, optional)
+- executors (array, optional): executor list.
+
+Typical fields per executor item:
+
+- executor (string, required): executor type.
+- configuration (object, optional): executor config map.
+
+Returns:
+
+- Promise<void|object>: usually no content (204), or response payload if provided by server.
 
 ## Feature Enablement
 
@@ -59,6 +125,27 @@ await KeycloakManager.clientPolicies.updatePolicies({}, {
     }
   ]
 });
+
+const profiles = await KeycloakManager.clientPolicies.getProfiles();
+
+await KeycloakManager.clientPolicies.updateProfiles({}, {
+  ...profiles,
+  profiles: [
+    ...(profiles.profiles || []),
+    {
+      name: 'pkce-profile',
+      description: 'Profile with PKCE related executors',
+      executors: [
+        {
+          executor: 'pkce-enforcer',
+          configuration: {
+            'pkce-enforcer.enforce.client': 'true'
+          }
+        }
+      ]
+    }
+  ]
+});
 ```
 
 ## See Also