Keycloak group management API client.

Use GroupManager to create, list, and delete Keycloak groups on a kdb Insights Enterprise instance.

Example

from kxi.authorization.group import GroupManager

mgr = GroupManager(host="https://<host>", username="admin", password="<pass>")

# Create a group and list all groups
mgr.create("data-engineers")
groups = mgr.list()

# Delete by name or Group object
mgr.delete("data-engineers")

Classes:

• Group – A Keycloak group.
• GroupManager – REST client for Keycloak group management.

Group

Bases: BaseModel

A Keycloak group.

Attributes:

• id (str) – Keycloak group UUID.
• name (str) – Human-readable group name.

GroupManager

GroupManager(host, username, password, *, realm=None, timeout=15, session=None, **kwargs)

Bases: KeycloakPath, ApiClient

REST client for Keycloak group management.

Authenticates as an admin user and provides CRUD operations for Keycloak groups on the kdb Insights Enterprise realm.

Example

from kxi.authorization.group import GroupManager

mgr = GroupManager(
    host="https://<host>",
    username="admin",
    password="<pass>",
    realm="insights",
)

mgr.create("analysts")
group = mgr.get("analysts")
mgr.delete(group)

See Connection Parameters for shared constructor arguments.

Functions:

• create – Create a new group.
• delete – Delete a group by name or Group object.
• delete_by_id – Delete a group directly by its Keycloak UUID.
• get – Retrieve a group by name.
• list – List all groups in the realm.

Initialise the GroupManager with admin credentials.

Parameters:

• host (str) – Base URL of the kdb Insights Enterprise instance.
• username (str) – Keycloak admin username.
• password (str) – Keycloak admin password.
• realm (str | None) – Keycloak realm name. Defaults to the configured realm.
• timeout (int) – HTTP request timeout in seconds. Default: 15.
• session (Client | AsyncClient | None) – Optional pre-built httpx session (overrides credential auth).
• *kwargs* – Additional keyword arguments forwarded to the base client.

create

create(name)

Create a new group.

Parameters:

• name (str) – Name of the group to create.

Returns:

• – API response for the created group.

delete

delete(group)

Delete a group by name or Group object.

Resolves the group ID via get before deleting.

Parameters:

• group (str | Group) – Group name or Group object to delete.

Returns:

• – API response for the deletion.

delete_by_id

delete_by_id(group_id)

Delete a group directly by its Keycloak UUID.

Parameters:

• group_id (str) – Keycloak UUID of the group to delete.

Returns:

• – API response for the deletion.

get

get(grp)

Retrieve a group by name.

Parameters:

• grp (str | Group) – Group name or an existing Group object (returned as-is).

Returns:

• Group – Matching Group object.

Raises:

• NotFoundException – No group with the given name exists.

list

list(**kwargs)

List all groups in the realm.

Returns:

• – List of Group objects.