Skip to main content
Onyx permissions are based on groups. A user’s access is the combination of the permissions from every group they belong to, plus any scoped access they receive as a Group Manager.
This permission system is available in Onyx v4.7 and later. If you are using an older version, see Users and Groups before v4.7.
Migrating from the old Curator role model? See What’s Changing in Permissions. The main rule is simple: permissions expand. If a user belongs to multiple groups, Onyx adds those permissions together. Being in one group does not take away access granted by another group.

​
The Permission Layers

Think of permissions as layers. Each layer can add more access for a user.
Chat only — no search, no admin access
Core access for chat, search, and personal use
Scoped management for one group’s members and resources
Organization-wide permissions granted to every member of a group
Full workspace access
The layers show how far access reaches, not a strict ranking. A Group Manager and a group permission are different mechanisms: a Group Manager’s access always stays inside the groups they manage, while a group permission applies across the whole organization. Depending on what you grant, one is not automatically “more” than the other.

​
Default Groups

Onyx includes two default groups: Standard users are assigned to default groups based on their access level. Custom groups let you grant specific permissions to the users in that group.
Custom groups and configurable group permissions require a Business or Enterprise plan, or Onyx Cloud. Community Edition has the Admin and Basic groups only.
The Basic group has one permission you can change: Create User Access Token. It is on by default. Turn it off on the Basic group’s page to stop users from creating personal access tokens.
Because all access comes from groups, a user who belongs to no group at all has no permissions.

​
Service Accounts and Groups

A service account gets its access the same way a user does: from the groups it belongs to. You choose those groups in the Groups selector when you create the API key. A service account that belongs to no group can post to chat, but it cannot search and it cannot reach any admin page. Only service accounts land here; regular users always start in a group.
If an API key can chat but returns nothing from search, check whether its service account is in a group.

​
How Onyx Calculates a User’s Permissions

Onyx checks every group a user belongs to and combines the permissions from those groups. If the same user is also made a Group Manager from a group detail page, Onyx adds that scoped manager access too. For example, say Priya has these assignments: Priya receives all three sets of access. The Analytics Viewers group does not limit her Engineering manager access, and her Engineering manager access does not remove anything from Basic.

​
Group Permissions

Group permissions are granted to a group and apply to every member of that group.
Group permissions are organization-wide. If you grant Manage Connectors & Document Sets to a group, every member of that group can manage connectors and document sets across the workspace.
Common examples:
  • Give an IT administrators group Manage Connectors & Document Sets so they can manage all connectors.
  • Give a model operations group Manage LLMs so they can configure language models.
  • Give an analytics group View Query History so they can review query activity.
  • Give a developer platform group Manage Actions so they can maintain MCP and OpenAPI plugins.
You set these permissions on the group’s detail page in the Admin Panel. For a tour of where the Users and Groups pages live, see Users and Groups. Group Permissions panel showing a toggle for each available permission

​
Group Managers

A Group Manager is a user who can manage one specific group from that group’s detail page. Group Managers are useful when a team lead should manage their own team’s users and resources, but should not receive organization-wide admin powers. Scoped to the group they manage, a Group Manager can:
  • Add and remove members from that group.
  • Manage connectors and document sets shared only with that group.
  • Manage agents shared only with that group.
  • Manage skills shared only with that group.
  • Manage plugins through the agents shared with that group.
  • Restrict an MCP plugin to the groups they manage. They must select at least one of their groups.
A Group Manager cannot:
  • Manage resources that are not shared with a group they manage.
  • Make a resource public.
  • Share a resource with a group they do not manage.
  • Grant organization-wide permissions.
You promote a member to Group Manager from the member list on that group’s detail page. Edit Group member list with one member marked as Manager

​
Group Permission vs. Group Manager

​
Available Group Permissions

The following permissions can be assigned to custom groups:
View Agent Analytics is not scoped through Group Manager access. The permission can be granted to a group, but agent-level analytics still require the user to own the agent unless the user also has Manage Agents.
Community Edition has no group permission configuration, so Create Agents is available to everyone. The permissions in this table are configured per group on the Business and Enterprise plans.

​
Document Access Is Separate

Permissions decide what a user can do in the Admin Panel and which resources they can manage. Document visibility is still controlled by connector and resource access settings. Connectors can be:
  • Private: Visible only to the creator, plus any groups explicitly granted access.
  • Public: Visible to all Onyx users.
  • Auto-sync: Restricted using permissions synced from the source system.
  • Auto-sync, restricted: Synced permissions apply, and only members of the selected groups can see the documents. Turn on Restrict Access to Groups on the connector. An admin must first turn on Allow Group Restrictions on Permission-Synced Connectors on Security & Hardening. Requires a Business or Enterprise plan.
Group-based document access needs a Business or Enterprise plan. In Community Edition, a document is visible to its connector’s creator and to everyone when the connector is public.

​
Common Setups

​
Frequently Asked Questions

Yes. Service accounts receive permissions from their groups exactly like a user. Bot, anonymous, and external placeholder accounts are system-managed and are not managed like regular users.
Anonymous users only exist when anonymous access is enabled, and they can only reach the chat surface. They have no account and belong to no group, so they cannot be given permissions and never appear in the permission layers as a separate level.
Yes. Create a custom group and assign the permissions that match the role you want.