Groups, Projects, and RBAC

Some Kumo deployments enable role-based access control (RBAC). In those workspaces, SDK operations run inside a group and, for model-building objects, a project. Groups are typically managed by administrators. Projects define a boundary for tables, graphs, predictive queries, training jobs, and related assets.

Initialize with a group and project

The easiest way to work in an RBAC-enabled workspace is to pass group and project to kumo.init().

import kumoai as kumo
kumo.init(
    url="https://<customer_id>.kumoai.cloud/api",
    api_key="<api_key>",
    group="marketing",
    project="churn-modeling",
)
print(kumo.current_group())
print(kumo.current_project())

group and project may be either names or IDs. If you belong to exactly one group, the SDK selects it automatically when RBAC is enabled. If multiple groups are available, pass group= to kumo.init() or call set_group() before selecting a project.

Discover groups and projects

Use list_groups() to view the groups available to you. After selecting a group, use list_projects() to view its projects.

groups = kumo.list_groups()
for group in groups:
    print(group.id, group.name)
kumo.set_group("marketing")
projects = kumo.list_projects()
for project in projects:
    print(project.id, project.name)
kumo.set_project("churn-modeling")

Changing the active group clears the active project because projects belong to a specific group.

Create a project

Create a project inside the current group with create_project().

kumo.set_group("marketing")
project = kumo.create_project("holiday-campaign", is_private=False)
kumo.set_project(project)

is_private=False makes the project visible to all group members. is_private=True restricts visibility to the creator only, subject to workspace policy.

Use administrator-managed group connectors

In RBAC-enabled workspaces, group connectors are the only supported connector type. Administrators publish these shared connectors so users can read source tables without requiring direct access to connection credentials.

kumo.init(
    url="https://<customer_id>.kumoai.cloud/api",
    api_key="<api_key>",
    group="marketing",
    project="churn-modeling",
)
connectors = kumo.list_group_connectors()
for connector in connectors:
    print(connector.display_name, connector.source_type, connector.scope)
warehouse = connectors[0]
orders_src = warehouse.table("sales.orders")

A GroupConnector behaves like other SDK connectors: use table() or indexing to obtain a SourceTable, then build Kumo Table objects from it.

orders = kumo.Table.from_source_table(
    source_table=orders_src,
    time_column="created_at",
).infer_metadata()

Error handling

The SDK exposes RBAC-specific exceptions so callers can handle RBAC errors explicitly.

try:
    project = kumo.current_project()
except kumo.FeatureNotEnabledError:
    print("This workspace does not use RBAC")
except kumo.GroupNotSetError:
    print("Select a group before listing or creating projects")
except kumo.ProjectNotSetError:
    print("Select a project before creating project-scoped objects")

Common causes:

• FeatureNotEnabledError: RBAC is not enabled for this workspace, or RBAC_ENABLED=false was set to opt out.
• GroupNotSetError: The SDK needs a group context. Pass group= to kumo.init() or call kumo.set_group().
• ProjectNotSetError: The SDK needs a project context. Pass project= to kumo.init() or call kumo.set_project() after selecting a group.

Environment override

By default, the SDK detects RBAC support from the Kumo service. The RBAC_ENABLED environment variable can override that detection, which is useful for migration scripts and testing:

export RBAC_ENABLED=true   # force RBAC helper behavior on
export RBAC_ENABLED=false  # opt out even if the service advertises RBAC

Use this override carefully; most users should rely on server-side detection.

Recommended workflow

1. Initialize with group= and project= whenever possible.
2. Use list_group_connectors() instead of embedding warehouse credentials in notebooks.
3. Create separate projects for separate modeling efforts, experiments, or production assets.
4. Avoid switching groups halfway through a notebook unless you also intentionally select a new project.