Skip to main content
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 below).

​
What Replaces It

The new system is built from two pieces that work together:

Group permission

Granted to a group and applies organization-wide. Every member of the group manages all resources of that type.

Group Manager

Granted to a person for a single group. They manage only that group’s resources and members — see 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).
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.
PermissionAs a group permission (granted to the group)As a Group Manager (assigned per person, per group)
Manage Connectors & Document SetsEvery member can create and edit any connector and document set, organization-wideManages only connectors and document sets shared solely within the group(s) they manage — and can’t make them public
Manage AgentsEvery member can create and edit any agent, organization-wideManages only agents shared solely within the group(s) they manage — and can’t make them public
Manage ActionsEvery member can create and edit any custom tool / MCP server, organization-wideManages 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:
PermissionDescription
Manage LLMsAdd and update configurations for language models (LLMs).
Manage Connectors & Document SetsAdd and update connectors and document sets.
Manage ActionsAdd and update custom tools and MCP/OpenAPI actions.
Manage GroupsAdd and update user groups.
Manage Service AccountsAdd and update service accounts and their API keys.
Manage Slack/Discord BotsAdd and update Onyx integrations with Slack or Discord.
Create AgentsCreate and edit the user’s own agents.
Manage AgentsView and update all public and shared agents in the organization.
View Agent AnalyticsView analytics for agents the group can manage.
View Query HistoryView query history of everyone in the organization.
Create User Access TokenAdd 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 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

PermissionCan be scoped to a group?
Manage Connectors & Document SetsYes
Manage AgentsYes
Create AgentsYes
Manage ActionsYes — 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 roleMember of Admins group (full access)
Basic roleMember 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 roleGroup 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):
  • For the same per-group scoping a Curator had, make the user a Group Manager of their group(s) — see 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). You assign managers manually only for groups you create afterward.

​
What Happens Automatically During Upgrade

The upgrade migration handles the following automatically:
1

Admin users

All users with the Admin role are auto-joined to the Admins group. They retain full system access.
2

Basic users

All users with the Basic role are auto-joined to the Basic group. Their capabilities are unchanged.
3

Curators and Global Curators

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.
4

Default groups created

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.
5

Existing groups preserved

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.
6

Document access unchanged

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

  1. Verify the converted Group Managers: Confirm former Curators can still manage their groups’ connectors, document sets, and agents.
  2. 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.
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.