> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions & Roles

> In-depth guide to Noxus permissions, default roles, and custom role management

Noxus provides a Role-Based Access Control (RBAC) system that manages user access at both the organization and workspace levels. Each user has one organization-level role (controlling tenant-wide operations) and optionally a role per workspace (controlling what they can do inside that workspace).

***

## Role Scope

Roles in Noxus have two scopes:

* **Global roles** — apply across all workspaces. A user assigned a global role has the same workspace permissions in every workspace they belong to.
* **Workspace-scoped roles** — apply only to a specific workspace. Useful for giving a user different access levels in different workspaces.

***

## Default Roles

The following built-in role configurations cover the most common use cases. These can be used as starting points when creating roles for your organization.

### Organization Roles

| Role          | Description                                | Key permissions                                                                 |
| :------------ | :----------------------------------------- | :------------------------------------------------------------------------------ |
| **Org Admin** | Full control over the entire organization. | All org permissions: `users.*`, `workspace.*`, `org.*`, `settings_read`.        |
| **Org Base**  | Standard organization member.              | `users_read`, `workspace_read`, `workspace_write`, `org_read`, `settings_read`. |

### Workspace Roles

| Role       | Description                                | Key permissions                                                                                                                 |
| :--------- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Admin**  | Full control over a specific workspace.    | All workspace permissions including `workspace_admin`.                                                                          |
| **Editor** | Can create and manage AI resources.        | `flows_edit`, `flows_delete`, `flows_run`, `agents_edit`, `agents_delete`, `agents_run`, `kbs_edit`, `kbs_delete`, `kbs_query`. |
| **Reader** | Run and query resources, no modifications. | `flows_run`, `agents_run`, `kbs_query`.                                                                                         |

***

## Creating Custom Roles

If the default roles don't meet your needs, create custom roles with a specific set of permissions.

**Organization-level roles:**

1. Navigate to **Settings** → **Roles** → **Organization** tab.
2. Click **Create role**.
3. Provide a name and optional description.
4. Select the desired organization-level permissions.
5. Click **Save**.

**Workspace roles:**

1. Navigate to **Settings** → **Roles** → **Workspace** tab.
2. Use the workspace picker to choose a specific workspace or **All workspaces** (creates a global role).
3. Click **Create role**.
4. Provide a name and optional description.
5. Select the desired workspace-level permissions.
6. Click **Save**.

<Note>
  Roles created with **All workspaces** selected are global roles and apply to every workspace. Roles created for a specific workspace only apply to members of that workspace.
</Note>

***

## Assigning Roles to Users

Roles can be assigned when inviting a user or updated later in the user management section.

### At the Organization Level

1. Go to **Settings** → **Users**.
2. Select a user and click **Edit role**.
3. Choose the appropriate organization-level role.

### At the Workspace Level

1. Navigate to a specific workspace's **Settings** → **Users**.
2. Click **Add users** or edit an existing member's role.
3. Select the workspace-specific role.

***

## API Key Permissions

When creating a workspace API key you can optionally restrict it to a subset of workspace permissions. A key with no restrictions has full access to all workspace permissions. A restricted key can only be granted permissions the creating user already has.

For a full reference of permission keys, see [Permissions Overview](/core/concepts/permissions).