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.

Roles

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

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:

How roles map to capabilities

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

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.
• 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 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 — assign these roles to people.
• Audit log — see how role determines audit visibility.
• PII and data governance — the system_admin-only PII controls.