> Source: https://builder.ema.ai/v2/administration/governance-and-permissions
> Title: Governance and Permissions

# Governance and Permissions

Ema controls access with role-based access control (RBAC). Every user holds exactly one role per tenant, and each role bundles a fixed set of capabilities — fine-grained permissions such as `workflow.create` or `user.invite`. When a user takes an action, the platform checks whether their role grants the capability that the action requires. Roles and capabilities are defined by the platform; they are the same in every tenant.

This page is the reference for the role model. To assign roles to people, see [User management](/builder/v2/administration/user-management).

## Roles

A role is a named bundle of capabilities. Ema ships six assignable roles, ordered from most to least privileged:

Role

Name

What it's for

System Admin

`system_admin`

Full administrative control over the tenant, users, integrations, SSO, and content.

Builder Admin

`builder_admin`

Full build and admin capability across users and content.

User Admin

`user_admin`

Manage users and memberships inside the tenant.

Builder

`builder`

Create and edit workflows, AI Employees, and knowledge bases.

User

`user`

Baseline end-user capabilities: run workflows, chat, and search.

No Access

`no_access`

Explicit deny — blocks all actions inside the tenant.

> [INFO]
> **About `env_admin`.** A seventh system role, `env_admin`, exists internally for the platform's feature-flag service. It is never assignable through the product surface, never appears in role pickers, and is filtered out of the roles reference. You will not encounter it when administering a tenant.

Roles are **cumulative** along the build and admin tiers. `builder` includes everything `user` can do; `user_admin` is `user` plus user-management capabilities; `builder_admin` is the union of `builder` and `user_admin` plus admin extras; `system_admin` is `builder_admin` plus the top tier of tenant, SSO, API-key, and audit capabilities. `no_access` grants nothing.

## Capabilities

A capability is a single permission, named `<group>.<action>` (for example `knowledge_base.create`). Capabilities are organized into groups. The capability is what an action actually checks for — a route that creates a workflow requires `workflow.create`, regardless of which role the caller holds.

The full taxonomy:

Group

Capabilities

tenant

`tenant.view`, `tenant.create_child`, `tenant.view_children`, `tenant.manage_settings`, `tenant.delete`

user

`user.invite`, `user.view`, `user.update`, `user.deactivate`, `user.delete`, `user.assign_role`, `user.revoke_membership`

role

`role.view`, `role.create`, `role.edit`, `role.delete`

sso

`sso.manage_config`, `sso.manage_domains`

auth

`auth.manage_api_keys`

workflow

`workflow.view`, `workflow.create`, `workflow.edit`, `workflow.delete`, `workflow.execute`, `workflow.view_runs`, `workflow.manage_access`

agent

`agent.view`, `agent.create`, `agent.edit`, `agent.delete`, `agent.execute`, `agent.test_execute`

knowledge\_base

`knowledge_base.view`, `knowledge_base.search`, `knowledge_base.create`, `knowledge_base.edit`, `knowledge_base.delete`, `knowledge_base.add_document`, `knowledge_base.delete_document`, `knowledge_base.tag_document`, `knowledge_base.manage_connector`, `knowledge_base.manage_taxonomy`

chat

`chat.session`, `chat.view_own`, `chat.edit_own`, `chat.feedback`, `chat.view_all`, `chat.manage_channels`

observability

`audit.view`, `metrics.view`, `eval.view`, `eval.configure`, `eval.execute`

feature\_flag

`feature_flag.view`, `feature_flag.manage`

integration

`integration.view`, `integration.install`, `integration.connect`, `integration.execute`

memory

`memory.view`, `memory.manage`

resource

`resource.share`, `resource.unshare`

> [INFO]
> **Reserved capabilities.** `role.create`, `role.edit`, and `role.delete` are declared for forward compatibility with custom roles but are not yet assignable — role mutation is not available in this version. `metrics.view` is reserved and has no backing endpoint yet.

## How roles map to capabilities

Each role grants a defined set of capabilities. The counts below are exact:

Role

Capabilities granted

`no_access`

0

`user`

19

`user_admin`

25

`builder`

33

`builder_admin`

44

`system_admin`

60

`system_admin` holds 60 of the 63 capabilities in the taxonomy. The three it does not hold are the reserved role-mutation capabilities (`role.create`, `role.edit`, `role.delete`), which are granted to no role in this version — see the reserved-capabilities note above.

### User (baseline)

The `user` role grants the capabilities an end user needs to run and consume content others have built:

`tenant.view`, `role.view`, `workflow.view`, `workflow.execute`, `workflow.view_runs`, `agent.view`, `agent.execute`, `knowledge_base.view`, `knowledge_base.search`, `knowledge_base.tag_document`, `chat.session`, `chat.view_own`, `chat.edit_own`, `chat.feedback`, `integration.view`, `integration.connect`, `integration.execute`, `feature_flag.view`, `memory.view`.

### Builder (build tier)

`builder` is `user` plus the capabilities to author content:

`workflow.create`, `workflow.edit`, `workflow.delete`, `agent.create`, `agent.edit`, `agent.delete`, `agent.test_execute`, `knowledge_base.create`, `knowledge_base.edit`, `knowledge_base.delete`, `knowledge_base.add_document`, `knowledge_base.delete_document`, `eval.view`, `eval.configure`.

### User Admin (user-management tier)

`user_admin` is `user` plus the capabilities to manage people:

`user.invite`, `user.view`, `user.update`, `user.deactivate`, `user.assign_role`, `user.revoke_membership`.

### Builder Admin (admin tier)

`builder_admin` is the union of `builder` and `user_admin`, plus:

`workflow.manage_access`, `eval.execute`, `chat.view_all`, `memory.manage`, `knowledge_base.manage_taxonomy`.

### System Admin (top tier)

`system_admin` is `builder_admin` plus the top-tier tenant, SSO, API-key, and audit capabilities — the full set needed to run the tenant (every capability except the three reserved role-mutation ones):

`tenant.create_child`, `tenant.view_children`, `tenant.manage_settings`, `tenant.delete`, `sso.manage_config`, `sso.manage_domains`, `auth.manage_api_keys`, `audit.view`, `metrics.view`, `feature_flag.manage`, `integration.install`, `knowledge_base.manage_connector`, `chat.manage_channels`, `user.delete`, `resource.share`, `resource.unshare`.

## How access is enforced

-   **Per-action checks.** Each API route is gated on the capability it needs. For example, listing memberships requires `user.view`; changing a role requires `user.assign_role`; viewing audit events requires `audit.view`.
-   **No privilege escalation.** When assigning or changing a role, the platform rejects any target role whose capability set is not a subset of your own effective capabilities. A `user_admin`, for instance, cannot promote someone to `builder_admin` because `builder_admin` includes build capabilities the `user_admin` does not hold. See [User management](/builder/v2/administration/user-management#role-assignment-rules).
-   **Resource-level grants.** Beyond role capabilities, specific resources can be granted to a user (for example per-workflow access via `workflow.manage_access`). These per-resource grants are checked in addition to the role's capabilities.
-   **Audit visibility follows role.** What a user sees in the [audit log](/builder/v2/administration/audit-log) depends on their role: `system_admin` and `user_admin` see all events; `builder_admin` and `builder` see build-resource events; `user` sees only their own actions; `no_access` sees nothing.

## Browsing roles and capabilities in the app

Open `/admin/roles` to browse the live role and capability reference. The page lists the system roles in a left column — the six above, in order from `system_admin` down to `no_access` (`env_admin` is hidden); selecting one shows its capabilities grouped by category, each with a description. A search box filters capabilities by name, description, or group. A badge marks whether a role is system-defined.

The data behind this page comes from three read-only endpoints on the auth service:

-   `GET /roles` — the assignable system roles.
-   `GET /roles/{id}/capabilities` — the capabilities bundled into one role.
-   `GET /capabilities` — the full capability taxonomy.

All three require the `role.view` capability, which every assignable role holds.

## What's next

-   [User management](/builder/v2/administration/user-management) — assign these roles to people.
-   [Audit log](/builder/v2/administration/audit-log) — see how role determines audit visibility.
-   [PII and data governance](/builder/v2/administration/pii-and-governance) — the `system_admin`\-only PII controls.