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 62 of the 65 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, metrics.view_scoped.

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, metrics.manage.

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, metrics.view_tenant_wide, 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 directly. For AI Employees, access resolves as the union of all containing scopes: the per-AI-Employee grant, the owning group's role, and the workspace role. A scope that contains the AI Employee grants access on its own; no other scope subtracts from it. This means a user granted Admin on one AI Employee can edit and manage it regardless of their workspace role, and the same grant is honoured on group-owned AI Employees. The one exception is the floor: no_access and external_chat_visitor are denied before any scope is consulted, so a deactivated user with a stale grant cannot regain access. AI Employee authors can share their own AI Employee with a group without needing a higher role.
• Per-AI-Employee grants on voice AI Employees. A workspace user with only the base user role who holds an explicit per-AI-Employee grant on a voice AI Employee now has that grant correctly enforced. Previously, voice AI Employee routes applied a workspace-role floor of builder or above before the per-AI-Employee gate was consulted, so the grant was silently ignored and the user received a 403. That floor has been removed from the read and test-call routes; the per-AI-Employee gate is the sole authority on those routes, matching how chat AI Employee access works. Edit, manage, and review routes (call transcripts, recordings, the generator surface) retain the builder-or-above floor, consistent with the grant tiers those actions require.
• 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.
• Metrics access is workspace-scoped. Viewing scoped usage metrics (one AI Employee or one group) requires metrics.view_scoped, held by every real role from user upward. Viewing tenant-wide metrics requires metrics.view_tenant_wide or a platform/workspace-admin role; cross-workspace visibility is bounded to the caller's own workspace plus its authorized sub-workspaces with no role carve-out.
• Voice AI Employee publish requires Edit permission. Publishing a voice AI Employee (making a version the live call flow) requires Edit-tier permission, not Manage. A user granted the builder role or a per-AI-Employee builder grant can publish. The Manage tier covers delete/restore, the Permissions tab, and the public toggle.

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.

Three settings are available:

• Instructions. Free-text instructions, up to 20,000 characters, 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.
• Skills. Workspace-global skills, uploaded as Markdown (.md) files of up to 1 MB, visible to every default Autopilot session in the workspace. Skills added here are not visible to bound orchestrator AI Employees.
• Web access. Enables or disables Autopilot's ability to search the web for all default Autopilot sessions in the workspace. 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.