> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/organizations-and-access/rbac.md).

# Multi-tenant RBAC

Multi-tenant RBAC scopes access to workspaces and grants roles to your identity provider groups through an RBAC policy.

{% hint style="info" %}
This page applies when your organization uses multi-tenant RBAC. You see a workspace switcher in the navigation bar, or an `Enforcing policy` banner on the `Users` tab. If you see neither, your organization uses basic permissions: read [Basic Permissions](https://docs.pipekit.io/organizations-and-access/basic-permissions.md) instead. If you plan to switch to multi-tenant RBAC, read on, then follow [Set Up Multi-tenant RBAC](https://docs.pipekit.io/organizations-and-access/rbac/set-up.md).
{% endhint %}

Multi-tenant RBAC splits your organization into workspaces and grants roles to your identity provider groups in each one. You define it in an RBAC policy file and publish it. To switch your organization to multi-tenant RBAC, ask your Pipekit account contact or email `hello@pipekit.io`. For the steps, refer to [Set Up Multi-tenant RBAC](https://docs.pipekit.io/organizations-and-access/rbac/set-up.md).

## Scope of enforcement

Pipekit enforces access at the Pipekit API and UI.

{% hint style="warning" %}
Pipekit RBAC does not constrain users who have direct `kubectl` or Argo UI access to a cluster. Kubernetes RBAC controls that access, and your platform team manages it.
{% endhint %}

## Workspaces

A workspace is a named scope that binds **one or more** `{cluster, namespace}` pairs and serves as the unit of access control. Every pipe, run, and template in Pipekit belongs to exactly one workspace. **Each `{cluster, namespace}` pair can only belong to one workspace.**

A user with access to `team-data` has no visibility into `team-ml`. For what a workspace scopes, refer to [Workspaces](https://docs.pipekit.io/organizations-and-access/rbac/workspaces.md). For how users switch between workspaces, refer to [Workspaces](https://docs.pipekit.io/using-pipekit/workspaces.md) in Using Pipekit.

## Roles

You assign each user or group one role per workspace. Bindings are additive. When a user holds access at both org scope and workspace scope, the higher-privilege role applies. The workspace roles rank from lowest to highest: Viewer, Runner, Editor, Workspace Admin. Org Admin is the exception: it grants no access inside a workspace. An Org Admin who needs to see runs, pipes, or templates also needs a workspace role, bound at org scope or on that workspace.

| Role                | Binding scope    | What they can do                                                                                                                    |
| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Org Admin**       | Org only         | Manage users, clusters, workspaces, SSO mappings, and role bindings across the entire organization                                  |
| **Workspace Admin** | Org or Workspace | Same actions as Editor in the current release. Future releases will add actions that only a Workspace Admin can take                |
| **Editor**          | Org or Workspace | Create, edit, and delete WorkflowTemplates and CronWorkflows; submit and manage workflow runs                                       |
| **Runner**          | Org or Workspace | Run templates and CronWorkflows that already exist; stop, retry, and resubmit runs. Cannot submit from the CLI, Hera, or Python SDK |
| **Viewer**          | Org or Workspace | Read-only access to pipes, runs, logs, and templates (no secrets visibility)                                                        |

Org Admin is the only role restricted to *org scope*, because it manages org-level entities that do not exist at workspace level.

### Runner

A Runner runs work that already exists in Pipekit, and nothing else. Grant Runner to support staff, other teams, or external users who run approved work.

#### What a Runner can do

* Run a template from `TEMPLATES`. The run uses the template's default branch and the entrypoint in its manifest. A Runner can set a value for each parameter that the template declares. To limit a parameter to approved values, list them in the parameter's `enum` in the template. Pipekit refuses a value outside the `enum` for every role. For the steps, refer to [Submitting a standalone template](https://docs.pipekit.io/using-pipekit/templates.md#submitting-a-standalone-template).
* Run a CronWorkflow now with `Run Now` on the Pipe's page, or with `pipekit trigger cron`. For the steps, refer to [Run a CronWorkflow now](https://docs.pipekit.io/using-pipekit/pipes/cron.md#run-a-cronworkflow-now).
* Stop and resubmit runs in the UI, and retry, restart, or stop a node in the node panel. For the details, refer to [Who can act on runs and nodes](https://docs.pipekit.io/using-pipekit/runs/inspect.md#who-can-act-on-runs-and-nodes).
* Run `pipekit stop`, `pipekit terminate`, `pipekit retry`, and `pipekit restart`. For the flags, refer to [Run actions](https://docs.pipekit.io/reference/cli/commands.md#run-actions-stop-terminate-restart-retry).

The [MCP server](https://docs.pipekit.io/ai/tool-inventory.md) calls the same Pipekit API as the CLI, so the same role checks apply. A Runner can use `trigger_cron`, `stop_run`, `terminate_run`, `restart_run`, and `retry_run` without parameter overrides. `submit_workflow` and `import_workflows` fail for a Runner.

#### What a Runner cannot do

A Runner cannot submit a workflow from the CLI, Hera, or the Python SDK. For the errors Pipekit returns, refer to [Submission enforcement](#submission-enforcement). A Runner cannot choose a template's version or entrypoint, or pass new parameters to `pipekit retry -p`. A template run that names a version, another entrypoint, or a parameter the template does not declare fails with `role_insufficient`. A Runner cannot create, edit, or delete pipes and templates. A Runner cannot call the REST API to start a pipe run at a git branch or tag. A Runner cannot create, update, suspend, resume, or delete CronWorkflows. A Runner cannot see or change secrets.

#### Restrict a workspace to approved work

To let a workspace run only approved work, grant Runner in it. Grant Editor and Workspace Admin to nobody in that workspace, at workspace scope or at org scope.

When a Runner runs a template, Pipekit uses the template's default branch. Anyone who can push to that branch decides what a Runner runs. Protect the default branch of each template repository, so that only reviewed changes reach it.

A Runner can also resubmit any earlier run in the workspace. A resubmit runs the same commit as the original run, even if a pull request or another branch started it. For a run submitted from the CLI, Hera, or the Python SDK, a resubmit runs the same manifest again. Run branches and pull requests that nobody has reviewed yet in a different workspace. Git events and schedules still start runs in the workspace.

## Groups and binding scopes

When a user's group membership changes in your identity provider, their Pipekit access updates automatically.

Bindings operate at two scopes:

* **Org scope** applies to all workspaces automatically. Use it for platform, ops, or admin groups that need cross-workspace access. One binding at org scope replaces one binding per workspace.
* **Workspace scope** applies to a single named workspace. Use it for team-level access where different groups need different roles in different environments.

```
# Org-scoped: applies to all workspaces
idp:team:platform        → Org Admin       → organization only
idp:team:ops             → Viewer          → all workspaces
idp:team:shared-tools    → Editor          → all workspaces

# Workspace-scoped: applies to one workspace only
idp:team:data-engineers  → Editor          → team-data-dev
idp:team:data-engineers  → Viewer          → team-data-prod
idp:team:support         → Runner          → team-data-prod
```

The role's action set is unchanged regardless of scope. For cross-workspace read-only access, for example a platform ops team that monitors all teams, bind Viewer at *org scope*.

When a user belongs to both an org-scoped group and a workspace-scoped group, the higher-privilege role applies:

```
idp:team:shared-tools  → Editor   → all workspaces
idp:team:foo           → Viewer   → team-foo-dev

# A user in both groups gets Editor in team-foo-dev, not Viewer
```

A workspace binding never reduces org-level access. If a group should not have elevated access in a specific workspace, do not give it an org-scoped role. Use explicit workspace bindings instead.

You can also bind a role to one user by email, for example a CI account. Group bindings are easier to maintain, because your identity provider keeps them current. To write a user binding, refer to [Publish RBAC Policy](https://docs.pipekit.io/organizations-and-access/rbac/publish-rbac-policy.md).

## Permission reference

| Action                                                              | Org Admin | WS Admin | Editor | Runner | Viewer |
| ------------------------------------------------------------------- | :-------: | :------: | :----: | :----: | :----: |
| **Org management**                                                  |           |          |        |        |        |
| Invite & remove users                                               |     ✓     |          |        |        |        |
| Manage clusters                                                     |     ✓     |          |        |        |        |
| Manage RBAC (workspaces, bindings, SSO mappings)                    |     ✓     |          |        |        |        |
| Manage alert providers                                              |     ✓     |          |        |        |        |
| Config as code                                                      |     ✓     |          |        |        |        |
| **Pipes**                                                           |           |          |        |        |        |
| View pipes & cron schedules                                         |           |     ✓    |    ✓   |    ✓   |    ✓   |
| Create / edit pipes                                                 |           |     ✓    |    ✓   |        |        |
| Delete pipes                                                        |           |     ✓    |    ✓   |        |        |
| Rotate pipe deploy key                                              |           |     ✓    |    ✓   |        |        |
| Manage pipe alert rules                                             |           |     ✓    |    ✓   |        |        |
| **Secrets**                                                         |           |          |        |        |        |
| View secret environments                                            |           |     ✓    |    ✓   |        |        |
| Create / edit secrets                                               |           |     ✓    |    ✓   |        |        |
| Delete secret environments                                          |           |     ✓    |    ✓   |        |        |
| **Runs**                                                            |           |          |        |        |        |
| View runs & logs                                                    |           |     ✓    |    ✓   |    ✓   |    ✓   |
| Submit workflows (CLI, Hera, Python SDK)                            |           |     ✓    |    ✓   |        |        |
| Import workflows from an Argo Workflow Archive                      |           |     ✓    |    ✓   |        |        |
| Start a pipe run at a git branch or tag (REST API)                  |           |     ✓    |    ✓   |        |        |
| Run templates and use `Run Now` on cron schedules                   |           |     ✓    |    ✓   |    ✓   |        |
| Choose a template's version and entrypoint                          |           |     ✓    |    ✓   |        |        |
| Retry with new parameters                                           |           |     ✓    |    ✓   |        |        |
| Cancel / retry / stop / resubmit runs                               |           |     ✓    |    ✓   |    ✓   |        |
| **Templates**                                                       |           |          |        |        |        |
| View templates                                                      |           |     ✓    |    ✓   |    ✓   |    ✓   |
| Manage workflow templates (create / edit / delete)                  |           |     ✓    |    ✓   |        |        |
| Manage cron schedules (create / update / suspend / resume / delete) |           |     ✓    |    ✓   |        |        |

To check the access each user has, refer to [Viewing access under a multi-tenant RBAC policy](https://docs.pipekit.io/organizations-and-access/members.md#viewing-access-under-a-multi-tenant-rbac-policy).

## How Pipekit enforces access

### Default-deny

Pipekit grants no access implicitly. A user must have an explicit workspace binding to interact with any pipe, run, or template in Pipekit. Namespaces added to a cluster are inaccessible to all users until an Org Admin explicitly binds them to a workspace.

### Workspace isolation in the UI

Users see only the workspaces they have access to. An Org Admin sees every workspace, but without a workspace role its lists stay empty. Pipes, runs, and templates from other workspaces are not visible. They are absent from all views, not hidden behind a permission error. Clusters are organization-level: only an Org Admin sees the `Clusters` list, and it shows every cluster in the organization.

### Submission enforcement

When you submit a workflow from the UI, CLI, or Python SDK, Pipekit checks that you have a binding in a workspace that covers the target cluster and namespace. If not, Pipekit rejects the submission before it reaches the workflow engine. To submit a workflow from the CLI, Hera, or the Python SDK, you need Editor or Workspace Admin in that workspace. A Runner who submits gets a `role_insufficient` error. A submission to a workspace where you have no role fails with a not-found error, such as `not found or no access`. A Runner can still run a template from the UI, as described in [Runner](#runner).

For a submission, Pipekit does not modify the workflow spec. It validates access and either allows or rejects the submission.

## Identity provider

Multi-tenant RBAC binds roles to groups your identity provider syncs through SCIM. Users who belong to no bound group can sign in, but they have no access. For setup, refer to [Set Up Multi-tenant RBAC](https://docs.pipekit.io/organizations-and-access/rbac/set-up.md), [Okta](https://docs.pipekit.io/organizations-and-access/sso/okta.md), and [Microsoft Entra](https://docs.pipekit.io/organizations-and-access/sso/entra.md).
