System Roles

7 min read

Overview

Gatekeeper ships with a predefined set of system roles that cover all areas of the Unique platform. These roles are read-only - they cannot be edited or deleted by administrators. They exist to ensure that all permissions from the previous Zitadel-based model continue to work seamlessly after Gatekeeper is enabled.

There are currently 25 system roles. The source of truth is the GatekeeperRoles enum (next/packages/backend/gatekeeper-utils/src/types/roles.ts) together with ROLE_DEFINITIONS (next/services/gatekeeper/src/roles/roles-definition/).

The tables below list every system role, grouped by functional area. Each table has four columns:

Role - the display name shown in the Access Management UI.
Role ID - the identifier used in Casbin policies and in the Gatekeeper admin API (adminGetAllRoles, adminAddGroupingPolicies). Use this value, not the display name and not the legacy Zitadel role name, when scripting role assignment.
Mapped from (legacy) - the Zitadel role, knowledge base permission, or scope access level that results in this role being assigned. Roles marked No legacy mapping are not derived from Zitadel.
What they can do - a summary of the permissions the role grants.

If you need a combination of permissions that no single system role provides, you can create a custom role that inherits from multiple system roles (see the parent page for details).

Company & administration

Role	Role ID	Mapped from (legacy)	What they can do
Company Administrator	`Company_Admin`	No legacy mapping (not synced from Zitadel)	Read, write and manage the company; full user administration. Inherits User Management Admin, KB Admin, Space Admin, Chat Admin, Benchmarking Admin, Feedback Admin, Analytics Admin, App Admin and Module Template Admin.
User Management Administrator	`User_Management_Admin`	Zitadel: `admin.user-management.write`	Create, change, delete and manage users; read, write, delete and list memberships; list groups. This role also gates access to the Access Management UI and to all `admin*` Gatekeeper queries and mutations.
Module Template Administrator	`Module_Template_Admin`	No legacy mapping	Read, write and delete modules; read, write, delete and manage module templates.

Chat

Role	Role ID	Mapped from (legacy)	What they can do
Chat Administrator	`Chat_Admin`	Zitadel: `chat.admin.all` (also grants KB Admin)	Company-wide chat administration: assistants, NPS, magic tables, due diligence, SoW assessments, MCP and MCP Hub (servers, OAuth providers, virtual server access), tools, groups, memberships, feature flags, company configuration, briefings, insights and installations. Inherits Chat user and Analytics Administrator.
Chat user	`Chat_User`	Zitadel: `chat.chat.basic`, `chat.chat.unlimited`	Use chat against their own data: chats, messages, message logs and assessments, own uploaded content, own prompts, own feedback, own magic tables, due diligence and SoW assessments, own spaces and assistants (read + chat), translations, notifications and own model usage.
Chat User (Debug)	`Chat_User_Debug`	Zitadel: `chat.debug.read` (also grants KB Viewer (Debug))	Everything Chat user can do, plus read and list chunks (chunk debug endpoints). Inherits Chat user.

Knowledge base

Role	Role ID	Mapped from (legacy)	What they can do
Knowledge Base Admin	`KB_Admin`	Zitadel: `chat.admin.all`; KB permission: Admin	Full knowledge base administration: read/write/delete/manage content, folders and scopes; manage scope access and scope-to-folder mappings; read/write/delete chunks; read reference statistics and ingestion metrics. Inherits KB Manager (used for role optimization only - the permission sets are identical today).
Knowledge Base Manager	`KB_Manager`	Zitadel: `chat.knowledge.write`; KB permissions: Can manage, Can write	Same permission set as KB Admin: access the knowledge base, upload files and folders, and manage permissions for accessible folders. Also intended for connectors (e.g. SharePoint) that need reliable knowledge base uploads.
Knowledge Base User	`KB_Viewer`	Zitadel: `chat.knowledge.read`, `chat.data.admin`; KB permission: Can read	Read and list content, folders and chunks; read, list and delete scopes; list users, memberships and groups; read the theme; manage their own notifications.
Knowledge Base Viewer (Debug)	`KB_Viewer_Debug`	Zitadel: `chat.debug.read` (also grants Chat User (Debug))	Everything Knowledge Base User can do, plus read and list chunks (chunk debug endpoints). Inherits Knowledge Base User.
Knowledge Base Metadata Editor	`KB_Metadata_Editor`	Zitadel: `chat.knowledge.metadata.edit`	Edit metadata of knowledge base content. Note: this role carries no Casbin permission policies of its own - it is a marker role that sets the `canEditKnowledgeBaseMetadata` UI permission. It must be combined with a KB role that grants content access.

Spaces

Role	Role ID	Mapped from (legacy)	What they can do
Space Administrator	`Space_Admin`	Zitadel: `admin.space.write`; scope access: WRITE, MANAGE	Create and configure spaces company-wide: assistants, scopes and scope access, modules and module templates, prompts, resource access, memberships, MCP tool configuration, installations and user prompts. Reads folders, content, tools, assistant types, groups and users.
Space Owner	`Space_Owner`	No legacy mapping - assigned in Unique, not synced from Zitadel	Create spaces and fully control their own assistants; read/list/write/manage scopes; manage modules, module templates and prompts; grant resource access. Sets the `canManageOwnSpace` UI permission.
Space Manager	`Space_Manager`	Derived automatically - assigned to any user or group that holds MANAGE access on at least one assistant	Read assistants and resource access; read and write language models; read/list/delete scopes; read and list folders and content; read modules, module templates, tools, assistant types, prompts; read and list users and groups; read/write/delete MCP tool configuration. Removed automatically when the last MANAGE access is revoked.

Apps & connectors

Role	Role ID	Mapped from (legacy)	What they can do
App Administrator	`Apps_Admin`	Zitadel: `admin.app-repository.write`	Create, update, delete and manage apps, API keys, installations, endpoints, request logs, logs and event subscriptions.
App Viewer	`App_Viewer`	No legacy mapping	Read apps, API keys, installations, endpoints, request logs and logs.
Connector Administrator	`Connector_Admin`	Zitadel: `connector.admin.write`	Full MCP connector management (create, read, list, write, delete, manage). Also lists users and groups, so admins can search principals in the MCP server access dialog.
Connector Viewer	`Connector_Viewer`	Zitadel: `connector.admin.read`	Read and list MCP connectors - open the MCP admin section and see the connector list.
MCP Server Manager	`Mcp_Server_Manager`	Derived automatically - assigned to any user or group granted access to at least one MCP server	Lists MCP servers. Per-server read/write rights come from instance-scoped policies (`resource:mcp:<serverId>`) rather than from this role. Removed automatically when the entity has no remaining MCP server policies.

Analytics, feedback & benchmarking

Role	Role ID	Mapped from (legacy)	What they can do
Analytics Administrator	`Analytics_Admin`	Zitadel: `chat.data.admin` (also grants Knowledge Base User)	Read chat interaction analytics (aggregated and detailed), user chat exports, active users and reference statistics; read and write the analytics scheduler; read and write model usage; read feedback; delete chats, companies and scopes (data deletion flows).
Feedback Administrator	`Feedback_Admin`	No legacy mapping	Read, write and delete feedback; read model usage costs.
Feedback Viewer	`Feedback_Viewer`	Zitadel: `chat.feedback.read` (also grants Benchmarking Viewer)	Read feedback and NPS responses; read the analytics scheduler, active users and chat interaction analytics (aggregated and detailed); read benchmarks and model usage. Read-only - cannot write or delete feedback.
Benchmarking Administrator	`Benchmarking_Admin`	No legacy mapping	Read, write and manage benchmarks - upload benchmarking sheets, download results and delegate benchmarking rights.
Benchmarking Viewer	`Benchmarking_Viewer`	Zitadel: `chat.feedback.read` (also grants Feedback Viewer)	Read benchmarks - download benchmarking sheets and results.

Compliance

Role	Role ID	Mapped from (legacy)	What they can do
Compliance Records Viewer	`Compliance_Records_Viewer`	Zitadel: `compliance.records.read`	Read compliance records.

Inheritance

Only five system roles inherit from others. Inheritance is transitive, so a user with Company Administrator effectively holds everything below it.

Role	Inherits
`Company_Admin`	`User_Management_Admin`, `KB_Admin`, `Space_Admin`, `Chat_Admin`, `Benchmarking_Admin`, `Feedback_Admin`, `Analytics_Admin`, `Apps_Admin`, `Module_Template_Admin`
`Chat_Admin`	`Chat_User`, `Analytics_Admin`
`Chat_User_Debug`	`Chat_User`
`KB_Viewer_Debug`	`KB_Viewer`
`KB_Admin`	`KB_Manager` (role optimization only - permission sets are identical)

All other system roles stand alone. In particular there is no Group Administrator role and no Space Viewer role; group permissions are granted directly on Chat Administrator, and Space Administrator has no parent role.

How roles get assigned

Assignment source	Roles
Synced from Zitadel on login and on role change (`zitadelManagedRoles()` in `access.service.ts`)	`Chat_User`, `Chat_User_Debug`, `KB_Viewer`, `KB_Viewer_Debug`, `KB_Admin`, `KB_Manager`, `KB_Metadata_Editor`, `Chat_Admin`, `Analytics_Admin`, `Feedback_Viewer`, `Benchmarking_Viewer`, `User_Management_Admin`, `Space_Admin`, `Apps_Admin`, `Connector_Admin`, `Connector_Viewer`, `Compliance_Records_Viewer`
Derived from access grants - added and removed automatically by the platform	`Space_Manager` (MANAGE access on an assistant), `Mcp_Server_Manager` (access on an MCP server)
Assigned inside Unique - via Access Management, the Gatekeeper admin API, or scope-management	`Company_Admin`, `Module_Template_Admin`, `Space_Owner`, `Feedback_Admin`, `Benchmarking_Admin`, `App_Viewer`

Only roles in the first group are reconciled against Zitadel. Roles in the second and third groups are never removed by Zitadel role sync.

Notes

Scope access READ is intentionally unmapped. Scope access levels WRITE and MANAGE map to Space_Admin; READ maps to no role, because no view-only space role exists yet.
Ownership scope. Roles such as Chat user and Space Owner declare owner: 'own' on most resources. This is stored in Casbin as subject:own, but runtime ownership is still enforced in the service and query layer rather than by Gatekeeper. See How to Create a New System Role for details.
Feedback Viewer and user-sensitive data. An earlier version of this page stated that Feedback Viewer cannot see prompts or other user-sensitive data. That distinction is not expressed in the role's Casbin policies - the role holds read access to detailed chat interaction analytics - so treat any such restriction as service-level behavior to be confirmed with the owning team rather than as a role guarantee.