Governance and Permissions

Ema controls access with role-based access control (RBAC). Every user holds exactly one role per workspace, 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 workspace.

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 workspace (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. AI Employee authors can share their own AI Employee with a group without needing a higher role; the platform grants share rights on resources you own.
• 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.

Workspace Management settings

Workspace Management (accessible to system_admin users) includes two areas that affect platform-wide behavior beyond individual user roles.

Autopilot tab

The Autopilot tab in Workspace Management lets a system_admin configure a workspace-level default for the Autopilot assistant. Settings saved here apply to every unbound Autopilot session in the workspace, sessions not tied to a specific orchestrator AI Employee. Bound orchestrator sessions run on their own published profile and are unaffected.

Two settings are available:

• Additional instructions. Free-text instructions appended to the Autopilot system prompt for every default session in the workspace. Use this to add workspace-specific guidance, terminology, or constraints without modifying individual AI Employee configurations.
• Platform tool toggles. Enable or disable platform-level tool groups (for example, web access) for all default Autopilot sessions in the workspace. The same toggle semantics apply as in the AI Employee builder: disabling web access also removes the Twitter/X search tool.

Changes take effect on the next turn of any affected session. There is no publish step and no session restart required.

Child workspace creation

Creating a child workspace under the current workspace is controlled by a per-workspace feature flag. The Create child workspace action in Workspace Management is only available when this flag is enabled for the workspace. Contact your Ema administrator to enable it.

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.