# Roles and Permissions

Understand seeded roles, custom roles, inheritance, and catalog permissions.

SteelEngine uses policy-based access control (PBAC). A role is a named collection of permissions from the [Permission Catalog](/permissions/permission-reference), not a hard-coded access level. You can assign roles to people or groups for one workspace or for the entire organization.

The old Read, Write, and Admin workspace levels were migrated to the seeded Viewer, Editor, and Workspace Admin roles. Existing access was converted automatically; new access is granted with roles.

## Default roles

Every organization starts with six seeded roles. They provide useful defaults and participate in the same policy system as custom roles.

### Organization roles

| Default role   | Initial purpose                                                                                                         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Admin**      | Full organization authority, including organization settings, access management, billing, and workspace administration  |
| **Supervisor** | Read the organization, create workspaces, and manage workspace membership without automatic access to workspace content |
| **Member**     | Read the organization, create workspaces, and use shared credential sets                                                |

### Workspace roles

| Default role        | Initial purpose                                                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Admin** | Viewer and Editor capabilities plus workspace settings, membership, API keys, credentials, inbox, and MCP administration      |
| **Editor**          | Viewer capabilities plus workflow, document, table, knowledge, tool, skill, and notification mutations                        |
| **Viewer**          | Read workspace content, workflows, documents, tables, knowledge, credentials metadata, tools, skills, and MCP server metadata |

The seeded hierarchy starts as:

```txt
Member → Supervisor → Admin
Viewer → Editor → Workspace Admin
```

A role on the right inherits the permissions of the role to its left. Organization administrators can edit role names, permissions, and inheritance, so treat the table as the initial configuration rather than an immutable product rule.

SteelEngine blocks any role edit, assignment removal, or member removal that would leave the organization without at least one person able to manage both authorization and organization membership.

## Seeded role grants

The seeded roles start with the grant sets below. Each workspace role includes the grants of the role before it in the hierarchy. Editor holds every Viewer grant, and Workspace Admin holds both.

| Role                | Initial grants                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**           | Every action on every object in the organization, including administration of all its workspaces                                                                                                                                                                                                                                                                                                            |
| **Supervisor**      | Read the organization, create workspaces, read and manage the members of any workspace, and manage your own personal data                                                                                                                                                                                                                                                                                   |
| **Member**          | Read the organization, create workspaces, read shared credential sets, and manage your own personal data                                                                                                                                                                                                                                                                                                    |
| **Viewer**          | Read everything in the workspace: workflows, documents, folders, chats, knowledge bases and their search results, databases and tables (including query and export), logs, jobs, apps, memory, credential metadata, environment variable names, API keys, tools, skills, and MCP and A2A metadata                                                                                                           |
| **Editor**          | Viewer, plus create, edit, and delete workspace content: workflows (including deploy and execute), documents, notifications, knowledge bases, databases and tables, custom tools, skills, jobs, and A2A agents. Editors also create and edit folders and apps, update chats, manage environment variables and memory, use and share credentials, and use built-in tools. They cannot delete folders or apps |
| **Workspace Admin** | Editor, plus administer the workspace: settings, members, API keys, credentials, the inbox, MCP servers and tools, BYOK keys, environment variable values, and promotion releases. Workspace Admins can also delete the workspace, folders, and apps                                                                                                                                                        |

No seeded role holds `workspace:promotion_attest`. Grant it through a custom role. Like the role names, these grant sets are the initial configuration. Administrators can edit them.

Organization release repositories and upstream branches use the separate `organization:promotion_repository_configure` permission. Admins have it by default. To delegate configuration, grant it at organization scope and provide read access to the managed workspaces. Workspace Admin, Supervisor, and Member access alone cannot change these settings. This delegation does not grant signing-key or promotion trust administration.

Workspace repository connections use **Manage source control** (`workspace:manage_source_control`) or effective **Manage settings** authority. Workspace and organization administrators can change the connection, lock or unlock its branch, and change editing and deployment policies. A custom role can delegate only source control management at one workspace's scope. Workspace readers can inspect the saved connection; source and destination organizations authorize repository access independently. This workspace permission is separate from the organization-release repository permission above.

Workspace Admin also includes `workspace:manage_integration_apps` and the `integration_app` permissions for [Custom Apps](/credentials/custom-apps). App management and credential access are separate. A shared app does not grant access to another person's Slack user token.

Some actions also have surface restrictions. For example, `database:delete` permits deleting an empty database from the dashboard or through the separately authorized [workload configuration contract](/self-hosting/entra-workload-identities#logical-database-and-table-configuration). Ordinary Chat, user/API-key MCP, scheduled Sub Agents and workflow tools cannot delete databases. Table deletion uses the separate `table:delete` permission.

## Custom roles

Custom roles let you model a job instead of choosing a broad tier. For example:

* A content operator can read and update documents without changing workflows.
* A release manager can read workflows, execute them, and deploy them without managing workspace members.
* A data analyst can query tables and databases without changing their schema.
* An MCP operator can read and manage MCP server connections without seeing credentials.

Create custom roles from **Organization Settings → Access → Roles**. Choose permissions by resource family and action, optionally add inherited roles, then review the impact preview before saving.

Each permission has a stable catalog key such as:

```txt
workspace:read_documents
workspace:update_documents
workflow:execute
table:query
mcp_server:manage
```

Role names are for people. Enforcement uses the permission grants attached to the role, so renaming a role does not change what it can do.

## Role inheritance

A role can inherit one or more other roles. The child receives its own grants plus all grants from its parents, including transitive parents.

Use inheritance for reusable layers:

1. Create a baseline role such as **Workspace Reader**.
2. Create **Document Editor** and inherit Workspace Reader.
3. Add only document create and update permissions to Document Editor.

SteelEngine prevents inheritance cycles and shows who would gain or lose access before an inheritance change is applied.

## Assignments and scope

A role does nothing until it is assigned. An assignment has four parts:

| Part    | Meaning                                                              |
| ------- | -------------------------------------------------------------------- |
| Subject | A person or permission group                                         |
| Role    | A seeded or custom role                                              |
| Scope   | The entire organization or one workspace                             |
| Source  | Direct assignment, group assignment, or organization-wide assignment |

An organization-wide assignment applies anywhere its role's grants match. A workspace assignment applies only to that workspace. Assigning a role does not copy its permissions; edits to the role affect every assignment that uses it.

## Effective access

Effective access is calculated at request time from all applicable paths:

* Direct roles assigned to the person
* Roles inherited through permission groups
* Organization-wide roles
* Workspace-scoped roles for the target workspace
* Permissions inherited by each role
* Explicit deny policies, when present
* Product-plan and entitlement requirements
* API-key scope caps for authenticated API and MCP requests

Allows are additive, but an applicable explicit deny wins over an allow. See [How Effective Access Is Calculated](/permissions/effective-access) for examples and troubleshooting.

## Workload identities

A deployment application registered under **Organization settings → Workload identities** uses its own workload principal and selected local catalog grants. It receives no human role assignment or membership. Its Entra application role permits entry to the workload authentication path; SteelEngine grants determine the allowed operations and targets.

`organization:manage_workload_identities` permits signed-in human management of these bindings. Future-workspace access additionally requires organization administration and delegation checks. A closed subset of deployment and resource-configuration actions is supported, with independent connector/credential/provider grants and separately selected cleanup. See [Entra workload identity setup and minimum grants](/self-hosting/entra-workload-identities).

## Workspace ownership

Creating a workspace creates a visible Workspace Admin assignment for its creator. Ownership remains part of the workspace record, but it is not a separate hidden authorization bypass. Access is explained by the creator's role assignment like any other member's access.

## Personal organizations

When an account has no organization membership and no actionable workspace invitation to open, SteelEngine creates a personal organization with a default workspace. The creator receives the seeded Admin role for the organization and Workspace Admin for the workspace. A personal organization uses the same role, assignment, and policy model as a team organization.

Existing members are routed to an organization they have permission to read. If none of their memberships grants read access, SteelEngine shows a no-access page instead of creating another personal organization. Membership alone does not override the current policy.

## Common Questions

**Are Viewer, Editor, and Workspace Admin fixed permission levels?**

No. They are seeded roles. They start with familiar read, edit, and administration permission sets, but authorized administrators can change their names, grants, and inheritance. Enforcement always follows the current grants.

**What is the difference between an organization role and a workspace role?**

The difference is the permissions and assignment scope, not a separate authorization engine. Organization roles usually carry governance permissions and are assigned organization-wide. Workspace roles carry resource permissions and are usually assigned to one workspace. Custom roles can combine catalog permissions to match your operating model.

**Can one person have several roles?**

Yes. Applicable assignments are combined. A person can hold an organization-wide role, a workspace-specific role, and roles inherited through groups at the same time.

**What happens when a role changes?**

Every assignment using that role sees the new effective permissions. The Roles tab shows an impact preview before a grant or inheritance change is saved.

**Can I accidentally remove the last access administrator?**

No. SteelEngine simulates sensitive role, assignment, and member changes and blocks a change that would leave no member with both authorization-management and member-management authority.

**Do API-key read, write, and admin scopes replace roles?**

No. Those labels are a transport-level cap on a key. The key owner must still have the required PBAC permission. A request is allowed only when both the owner policy and the key scope allow it.
