> ## Documentation Index
> Fetch the complete documentation index at: https://kumo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups, Projects, and RBAC

> Scope Kumo SDK work to groups and projects in RBAC-enabled workspaces

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.

<Info>
  RBAC APIs are only available when RBAC is enabled for your workspace. If RBAC is disabled, these helpers raise `FeatureNotEnabledError` and SDK objects are not scoped by group or project.
</Info>

## 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()`.

```python theme={null}
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 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.

```python theme={null}
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()`.

```python theme={null}
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 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.

```python theme={null}
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.

```python theme={null}
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 automation can fail clearly.

```python theme={null}
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. For migration scripts, `RBAC_ENABLED` can override that detection:

```bash theme={null}
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.