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 usually managed by administrators. Projects provide a workspace 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().

1
import kumoai as kumo
2
3
kumo.init(
4
    url="https://<customer_id>.kumoai.cloud/api",
5
    api_key="<api_key>",
6
    group="marketing",
7
    project="churn-modeling",
8
)
9
10
print(kumo.current_group())
11
print(kumo.current_project())

group and project may be either names or IDs. If your user belongs to exactly one group, the SDK auto-selects that group when RBAC is enabled. If multiple groups are available, pass group= during initialization or call set_group() before selecting a project.

Discover groups and projects

Use list_groups() to see groups available to the authenticated user. After selecting a group, use list_projects() to see projects in that group.

1
groups = kumo.list_groups()
2
for group in groups:
3
    print(group.id, group.name)
4
5
kumo.set_group("marketing")
6
7
projects = kumo.list_projects()
8
for project in projects:
9
    print(project.id, project.name)
10
11
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().

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

is_private=False makes the project visible to members of the group. Set is_private=True for a project visible only to its creator, subject to workspace policy.

Use administrator-managed group connectors

In RBAC-enabled SDK workspaces, group connectors are the only supported connector type. Administrators publish these shared connectors so SDK workflows can read source tables without exposing connection details or credentials to users.

1
kumo.init(
2
    url="https://<customer_id>.kumoai.cloud/api",
3
    api_key="<api_key>",
4
    group="marketing",
5
    project="churn-modeling",
6
)
7
8
connectors = kumo.list_group_connectors()
9
for connector in connectors:
10
    print(connector.display_name, connector.source_type, connector.scope)
11
12
warehouse = connectors[0]
13
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.

1
orders = kumo.Table.from_source_table(
2
    source_table=orders_src,
3
    time_column="created_at",
4
).infer_metadata()

Error handling

The SDK exposes RBAC-specific exceptions so automation can fail clearly.

1
try:
2
    project = kumo.current_project()
3
except kumo.FeatureNotEnabledError:
4
    print("This workspace does not use RBAC")
5
except kumo.GroupNotSetError:
6
    print("Select a group before listing or creating projects")
7
except kumo.ProjectNotSetError:
8
    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. For migration scripts, RBAC_ENABLED can override that detection:

$
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.