Roles & Permissions

The Roles & Permissions screen (Admin → Roles & Permissions, /admin/roles) defines what users are allowed to do. Access requires the ROLE_MANAGE permission.

Access control has two layers, both edited here:

Layer Question it answers

Permissions

May this role do X at all? — e.g. create Topics, manage servers, view metrics

Resource Access

Which specific Topics, GraphRAG Topics, Agents, and Pipelines may this role see?

Holding TOPIC_VIEW does not imply access to every Topic — the second layer narrows it down.

1. Screen layout

Two panels side by side:

  • Left — Roles: the list of roles with their descriptions, a built-in badge where applicable, and a New Role button.

  • Right — Permissions: appears once you select a role. Permission checkboxes grouped into cards, the Resource Access section below, and Save Changes / Delete Role in the header.

Nothing is saved until you press Save Changes.

2. The built-in roles

A fresh installation is seeded with two roles, both flagged built-in:

Role Description Contents

ADMIN

Full system access

Every permission, including all admin areas

USER

Standard user access

Topics, GraphRAG Topics, Agents, Pipelines (view/create/edit/delete/start/chat/upload), MCP tools, own profile, and log reading — but no admin permissions

Built-in roles behave differently from custom ones:

Built-in Custom

Rename

No

No (name is fixed at creation)

Change permissions

ADMIN: no — checkboxes are disabled and Save is greyed out with the tooltip "Built-in ADMIN role always has all permissions". USER: yes

Yes

Delete

No — the Delete button is disabled

Yes

ADMIN is deliberately immutable so an installation cannot be locked out of its own administration.

3. Permission groups

Permissions are grouped into cards, each checkbox with a short description:

Group Permissions

Topics & Chat

View · Create · Edit · Delete · Start/Stop · Chat · Upload Documents

GraphRAG Topics & Chat

View · Create · Edit · Delete · Start/Stop · Chat · Upload Documents (also deleting documents and recomputing communities)

Agents

View · Create · Edit · Delete · Start/Stop · Chat

Pipelines

View · Create · Edit · Delete

MCP & Profile

View MCP Tools · Edit Own Profile

Server Infrastructure

View Servers · Manage Servers

User & Role Management

View Users · Manage Users · Manage Roles

System Configuration

View LLM Config · Manage LLM Config · Auth Settings · View Metrics · Download Deployment Files (the Docker Compose or Kubernetes file of a Topic, GraphRAG Topic or Agent on its Actions tab; it holds every password and key, such as model and database keys, the license and, for an Agent, the client secret its scheduled runs act with — admin role only)

API

API Access — use the REST API with a Bearer token

Logs

Read Topic Logs · Read All Users' Topic Log Lines · Read Agent & GraphRAG Logs · Read All Users' Agent & GraphRAG Log Lines — the Logs tab of Topics, GraphRAG Topics and Agents. With Read Topic Logs (Read Agent & GraphRAG Logs) alone a user sees the lines of their own questions and uploads and the lines that belong to no user; Read All Users' Topic Log Lines (Read All Users' Agent & GraphRAG Log Lines), admin role only, adds everyone else’s

DEV Reporting

Use DEV Reporting · Read All Users' DEV Reports — switch per-operation reports (ingestion, retrieval/chat, pipeline runs) on a container and read them. Reports contain full prompts and document content; not part of the default USER role. On a Topic, GraphRAG Topic or Agent everyone sees only their own reports (a scheduled pipeline run’s belong to the pipeline’s owner); the second permission (admin role only) shows everyone’s

Every permission that exists has a checkbox here. Save Changes stores exactly the ticked boxes.

The View/Manage split

Most admin areas separate reading from changing. SERVER_VIEW shows AI servers, Docling servers, and vector databases but hides every Add/Edit/Delete button; SERVER_MANAGE adds them. The same pattern applies to CONFIG_VIEW/CONFIG_MANAGE and USER_VIEW/USER_MANAGE. This lets you grant read-only insight into the infrastructure without granting change rights.

Permissions the navigation menu depends on

The Admin menu group appears only if a role holds at least one of SERVER_VIEW, CONFIG_VIEW, USER_VIEW, ROLE_MANAGE, AUTH_MANAGE, or METRICS_VIEW — and each entry within it is shown individually per permission:

Permission Admin menu entries

METRICS_VIEW

Metrics

SERVER_VIEW

AI Servers · Docling Servers · Vector Databases · Graph Databases

CONFIG_VIEW

LLM Configuration · Prompt Templates · Public Endpoints · Mail Server · Mail Templates · License

USER_VIEW

User Management

ROLE_MANAGE

Roles & Permissions

AUTH_MANAGE

OIDC Settings

If a user reports a missing menu entry, the cause is almost always the corresponding permission in this table.

4. Resource Access

Below the permission cards, four cards list every existing resource with a checkbox each:

Card Contents

Topics

All Topics, by name

GraphRAG Topics

All GraphRAG Topics, by name

Agent Servers

All Agents, by name

Pipelines

All Pipelines, by name

Ticking an entry grants this role access to that specific resource. This is the second access layer: a role needs both the general permission (for example TOPIC_VIEW) and access to the individual Topic.

Resource assignments are saved together with the permissions when you press Save Changes.

New resources: when someone creates a Topic, GraphRAG Topic, Agent or Pipeline, it is granted automatically to the ADMIN role and to every role of its creator. Other roles do not get it. If members of another role should see it, tick it here, or in the access roles of the resource itself.

5. Creating and deleting roles

New Role

Opens a dialog with Role Name (required, must be unique) and Description (free text, shown under the name in the list).

The role is created with no permissions at all. Select it afterwards, tick what it needs, and press Save Changes. The name cannot be changed later — only the description, permissions, and resource assignments.

Delete Role

Only available for custom roles. A confirmation dialog warns that "Users assigned this role will lose its permissions."

Check for affected users first, under Admin → User Management — the Roles column shows who holds the role. Since every user must have at least one role, deleting the only role a user holds leaves that account without permissions.

6. Recommended setup

  1. Leave ADMIN untouched, and give it to as few people as possible.

  2. Decide whether USER fits your needs, and adjust it if not.

  3. Create purpose-built roles rather than widening USER — e.g. a READER role with TOPIC_VIEW
    TOPIC_CHAT + PROFILE_EDIT and resource access to a few Topics.

  4. For read-only oversight, combine the *_VIEW permissions without their *_MANAGE counterparts.

  5. Grant API_ACCESS only to accounts that genuinely drive the REST API from scripts.

  6. Whenever you add a Topic, GraphRAG Topic, Agent, or Pipeline, check that every role that should see it has it ticked under Resource Access. Only ADMIN and the creator’s roles get it automatically.

7. Troubleshooting

Symptom Cause and fix

Cannot open the screen

Your role lacks ROLE_MANAGE

Checkboxes greyed out, Save disabled

You selected the built-in ADMIN role, which always holds all permissions

Delete button greyed out

Built-in roles cannot be deleted

A user has TOPIC_VIEW but sees no Topics

Resource Access — no Topics are ticked for their role

A newly created Topic is invisible to a role

New resources are granted only to ADMIN and the creator’s roles. Tick it under Resource Access

The Logs tab says you have no access

The role lacks the matching permission in the Logs card: Read Topic Logs for Topics, Read Agent & GraphRAG Logs for Agents and GraphRAG Topics

A whole admin area is missing from the menu

The corresponding *_VIEW permission is not granted

Buttons visible but actions refused

A *_VIEW permission is granted without the matching *_MANAGE

Role name rejected

A role with that name already exists

Cannot rename a role

Names are fixed after creation. Create a new role and reassign the users

Related