> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.
# What's Changing in Permissions
> Onyx is moving to group-based permissions. Here's what's changing, what's being removed, and what you need to do.
This page describes an upcoming migration that will take effect in a future release. No action is required yet.
We are publishing this guide early so you can plan ahead.
## Why We're Changing
Onyx's current permission system offers limited flexibility. You can make someone an **Admin** (full access),
a **Basic** user (no management access), or a **Curator** (management access scoped to specific groups).
There's nothing in between. If you want someone to manage connectors but not agents,
or view analytics without any management access, the current system can't do that.
The new **group-based permission system** solves this by assigning permissions directly to groups.
Each group can have a specific set of permissions, and users inherit the permissions of every group they belong to.
This enables granular delegation. For example,
giving a team lead access to manage connectors without granting them full admin or curator powers.
It also preserves the **per-group scoping** Curators relied on — through **Group Managers** — so you get both
finer-grained permission types and the ability to delegate a single group's management. The next sections explain each.
## What's Being Removed
The following roles and features will be permanently removed in an upcoming release.
Please review your current setup and plan ahead.
* **Curator role**: Removed
* **Global Curator role**: Removed
* **`CURATORS_CANNOT_VIEW_OR_EDIT_NON_OWNED_ASSISTANTS`** environment variable: Removed
The Curator *roles* go away, but the *capability* they provided — scoped,
per-group management — is preserved through **Group Managers** (see [Group Managers](#group-managers) below).
## What Replaces It
The new system is built from two pieces that work together:
Granted to a **group** and applies organization-wide.
Every member of the group manages **all** resources of that type.
Granted to a **person** for a **single group**.
They manage only that group's resources and members — see [Group Managers](#group-managers).
Configurable group permissions and Group Managers rely on custom groups, which are an **Enterprise Edition** feature.
Community Edition keeps the two default groups, Basic and Admins (see the [FAQ](#frequently-asked-questions)).
Group permissions are more flexible than the old Curator model:
* You can grant **Manage Connectors & Document Sets** without granting agent management
* You can grant **View Agent Analytics** or **View Query History** without any management permissions
* You can create purpose-specific groups like "Content Managers" or "Analytics Viewers"
### Group permission vs. Group Manager
The two mechanisms can grant the **same permission name** — *Manage Connectors & Document Sets*, *Manage Agents*,
*Manage Actions* — but their reach is very different. This is the most important distinction to get right.
Enabling a **Manage X** permission *on a group* gives **every member** the **full,
organization-wide** ability to manage **all** resources of that type — not just the group's own resources.
It is **not** a way to scope management to a single group. To let someone manage only one group's resources,
make them a **Group Manager** of that group instead — don't grant the group-wide permission.
| Permission | As a **group permission** (granted to the group) | As a **Group Manager** (assigned per person, per group) |
| --------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Manage Connectors & Document Sets | Every member can create and edit **any** connector and document set, organization-wide | Manages only connectors and document sets shared **solely** within the group(s) they manage — and can't make them public |
| Manage Agents | Every member can create and edit **any** agent, organization-wide | Manages only agents shared **solely** within the group(s) they manage — and can't make them public |
| Manage Actions | Every member can create and edit **any** custom tool / MCP server, organization-wide | Manages the actions used by their managed group's agents — actions are scoped **through agents**, since tools and MCP servers have no direct group association |
In other words, a Group Manager can only act on a resource that lives **entirely** within the group(s)
they manage and stays **private** — visible only to those groups. They can't make a resource public, share it org-wide,
or attach it to a group they don't manage. A group-wide **Manage X** permission has none of these limits.
### Available Permissions
The following permissions can be assigned to any group:
| Permission | Description |
| --------------------------------- | ----------------------------------------------------------------- |
| Manage LLMs | Add and update configurations for language models (LLMs). |
| Manage Connectors & Document Sets | Add and update connectors and document sets. |
| Manage Actions | Add and update custom tools and MCP/OpenAPI actions. |
| Manage Groups | Add and update user groups. |
| Manage Service Accounts | Add and update service accounts and their API keys. |
| Manage Slack/Discord Bots | Add and update Onyx integrations with Slack or Discord. |
| Create Agents | Create and edit the user's own agents. |
| Manage Agents | View and update all public and shared agents in the organization. |
| View Agent Analytics | View analytics for agents the group can manage. |
| View Query History | View query history of everyone in the organization. |
| Create User Access Token | Add and update the user's personal access tokens. |
Some of these permissions can also be granted as *scoped* permissions to make someone a **Group Manager** of a single
group — see [Which permissions can be scoped](#which-permissions-can-be-scoped) below.
## Group Managers
A **Group Manager** is a member of a group who has been given management access to **a single group** — its resources
and its members — without organization-wide powers. Access is granted per user, per permission, per group.
For example: *Alice can manage connectors,
but only for the connectors shared with the Engineering group.* Alice does not become an organization-wide connector
admin; her management access stops at Engineering's resources.
### What a Group Manager can do
Scoped to the group(s) they manage, a Group Manager can:
* **View, edit, and remove** the **connectors**, **agents**, and **document sets** shared with the group.
* **Manage the actions** (custom tools and MCP servers) used by their group's agents.
* **Add and remove members** of the group.
* **Create** connectors, agents, and document sets — as long as each is shared with a group they manage.
A Group Manager **cannot**:
* Manage resources that aren't shared with a group they manage.
* **Make a resource public**, or extend its access beyond the groups they manage.
* Grant organization-wide permissions to anyone.
Credentials stay private. A Group Manager can see **which** credential a connector uses,
but can't view its secret values or reuse a credential they don't have access to when creating their own connectors.
(Unchanged by this migration.)
### Which permissions can be scoped
| Permission | Can be scoped to a group? |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Manage Connectors & Document Sets | Yes |
| Manage Agents | Yes |
| Create Agents | Yes |
| Manage Actions | Yes — scoped through the managed group's agents |
| All others (Manage LLMs, Manage Groups, View Agent Analytics, View Query History, Manage Service Accounts, Manage Slack/Discord Bots, Create User Access Token) | No — organization-wide only |
**Manage Actions** has no direct group association — custom tools and MCP servers aren't attached to groups directly.
A Group Manager's scoped action management is therefore derived from the **agents** in the group(s)
they manage (which *are* shared to groups), rather than from a tool-to-group link.
When scoped, **Create Agents** lets the manager create agents shared with their group.
Managing the **members and shared resources of a group you're assigned to** comes with being its Group Manager — it does
not require the organization-wide **Manage Groups** permission, which administers *all* groups.
There's no risk of lockout. An Admin can always view and reset a group's managers.
Removing a user from a group revokes their scoped permissions for that group,
and deleting a group removes any Group Manager grants tied to it.
## Before and After
| Old (Current System) | New (Group-Based Permissions) |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Admin role | Member of **Admins** group (full access) |
| Basic role | Member of **Basic** group (chat, search, personal agents) |
| Curator role (per-group) | **Group Manager** of their group(s) — scoped management of that group's connectors, document sets, agents, and members |
| Global Curator role | **Group Manager** in each group they manage, or group-wide Manage permissions when organization-wide access is intended |
### What changes for Curators
In the old system, a **Curator** could manage resources (connectors, agents, document sets)
and members **scoped to the specific group(s)** they curated.
A **Global Curator** had the same powers across all groups they belonged to.
That single role is now split into separate, individually grantable permissions,
and you choose the scope for each (see [What Replaces It](#what-replaces-it)):
* For the **same per-group scoping** a Curator had, make the user a **Group Manager** of their group(s) — see
[Group Managers](#group-managers).
* For **organization-wide** management, grant the permission to a group instead.
You don't have to do this by hand for existing groups: during the upgrade,
former Curators and Global Curators are **automatically converted** to Group Managers of the groups they managed (see
[What Happens Automatically During Upgrade](#what-happens-automatically-during-upgrade)).
You assign managers manually only for groups you create afterward.
## What Happens Automatically During Upgrade
The upgrade migration handles the following automatically:
All users with the **Admin** role are auto-joined to the **Admins** group. They retain full system access.
All users with the **Basic** role are auto-joined to the **Basic** group. Their capabilities are unchanged.
Existing **Curators** and **Global Curators** are automatically converted to **Group Managers** of the groups they
curated. Their per-group management carries over — there is no lockout,
and no manual reassignment for existing groups.
This automatic conversion covers only the groups that exist at upgrade time.
For any **new** group you create afterward, assign its Group Managers manually.
Two protected groups are automatically created:
* **Basic**: All users are auto-joined. Grants core platform access (chat, search, personal agents).
* **Admins**: All former Admin users are auto-joined. Grants full system access.
All your existing custom groups and their resource associations (connectors, document sets, agents) are preserved.
No group memberships are lost. You can then assign permissions to these groups after upgrading.
How documents appear in search results is not affected by this change.
Document-level access is still controlled by connector access types (Public, Private, Synced)
and group-to-resource associations, which remain the same.
## What You Need to Do
Existing Curators and Global Curators are migrated to **Group Managers** automatically,
so most setups need little manual work.
Your main job is to verify the result and decide how new groups are managed going forward.
### Before Upgrading
1. **Review your Curator assignments**: Note which users are Curators or Global Curators and which groups they manage,
so you can confirm the conversion afterward.
2. **Decide where you want organization-wide management**:
If a team should manage *all* resources of a type rather than a single group's,
plan to grant that permission to a group instead.
### After Upgrading
3. **Verify the converted Group Managers**: Confirm former Curators can still manage their groups' connectors, document
sets, and agents.
4. **Handle new groups going forward**: The migration only covers groups that existed at upgrade. For new groups, grant
group permissions and assign **Group Managers** manually.
## Timeline
Specific version numbers and dates have not been finalized yet.
This page will be updated as the release schedule is confirmed. Here is the planned rollout sequence:
1. **Now**: This documentation is published so you can understand the upcoming changes and start planning.
2. **Before the release**: Deprecation banners will appear in the Admin UI on the Users and Groups pages,
warning that Curator and Global Curator roles will be removed.
3. **On release**: The new group-based permission system ships.
Curator and Global Curator roles are permanently removed. Migration runs automatically on upgrade.
## Frequently Asked Questions
If you only use Admin and Basic roles, this change requires no action from you. Your users, groups,
and resources will continue to work exactly as they do today.
The new permission system gives you additional flexibility if you need it in the future.
All resources (connectors, document sets, agents) are preserved with their original ownership,
and the creator remains the owner.
Because former Curators become Group Managers of their groups during the migration,
they keep the ability to manage the resources shared with those groups.
Yes.
Assign the user as a **Group Manager** of the relevant group — they'll manage only that group's resources and
members, the same per-group scoping the old Curator role provided. See [Group Managers](#group-managers).
No. A Group Manager can only manage resources within the group(s) they manage.
They can't widen a resource's sharing to a group they don't manage,
and they can't remove a resource from its last group (which would leave it orphaned).
This keeps a manager's reach contained to their own group.
No. CE behavior is identical to today. CE has two default groups (Basic and Admins)
that mirror the current Admin/Basic role split.
Custom groups with configurable permissions are an Enterprise Edition feature.
Existing Admin API keys are placed in the Admins group. Basic API keys are placed in the Basic group.
After upgrading, you can assign service accounts to specific groups for more granular access.