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

# Authorization

> Scope-based authorization model for workspaces and organization-level administration

Noxus authorization is permission-driven and split between:

* **Workspace-level permissions** — govern what a user can do inside a specific workspace.
* **Organization-level permissions** — control cross-workspace and tenant-wide administration.

***

## Workspace-Level Permissions

These permissions are scoped to a workspace and stored as boolean flags on the user's workspace role.

| Category        | Permission key      | Description                                               |
| --------------- | ------------------- | --------------------------------------------------------- |
| Flows           | `flows_edit`        | Create and edit workflows                                 |
| Flows           | `flows_delete`      | Delete workflows                                          |
| Flows           | `flows_run`         | Execute workflows                                         |
| Flows           | `flows_advanced`    | Advanced workflow features (API deployment, versioning)   |
| Agents          | `agents_edit`       | Create and edit AI agents                                 |
| Agents          | `agents_delete`     | Delete agents                                             |
| Agents          | `agents_run`        | Chat with and execute agents                              |
| Agents          | `agents_advanced`   | Advanced agent features                                   |
| Knowledge Bases | `kbs_edit`          | Create, upload, and manage documents                      |
| Knowledge Bases | `kbs_delete`        | Delete knowledge bases                                    |
| Knowledge Bases | `kbs_query`         | Query and search knowledge bases                          |
| Knowledge Bases | `kbs_advanced`      | Advanced KB features (ingestion pipelines, etc.)          |
| Administration  | `integrations_edit` | Connect and configure external integrations               |
| Administration  | `users_edit`        | Invite and modify workspace members                       |
| Administration  | `users_delete`      | Remove members from the workspace                         |
| Administration  | `workspace_admin`   | Full workspace administration (settings, roles, API keys) |

### `workspace_admin` cascade behavior

`workspace_admin` is a superset of the other administration permissions. When a user or API key has `workspace_admin`, the authorization layer grants:

* Full **integrations** access (create, read, edit, delete) — equivalent to `integrations_edit` plus create/delete.
* Full **workspace users** access (create, read, edit, delete) — equivalent to `users_edit` plus `users_delete` plus create.

`integrations_edit` alone grants read and edit on integrations. `users_edit` alone grants read and edit on workspace members. `users_delete` alone grants delete on workspace members.

***

## Organization-Level Permissions

These permissions control tenant-wide operations and are checked independently of workspace membership.

| Category     | Permission key     | Description                                        |
| ------------ | ------------------ | -------------------------------------------------- |
| Users        | `users_read`       | View all users in the organization                 |
| Users        | `users_invite`     | Invite new users to the organization               |
| Users        | `users_edit`       | Modify user information                            |
| Users        | `users_delete`     | Remove users from the organization                 |
| Workspaces   | `workspace_read`   | View all workspaces                                |
| Workspaces   | `workspace_write`  | Create new workspaces                              |
| Workspaces   | `workspace_edit`   | Modify workspace settings                          |
| Workspaces   | `workspace_delete` | Delete workspaces                                  |
| Organization | `org_read`         | View organization details                          |
| Organization | `org_edit`         | Modify organization details                        |
| Organization | `org_billing`      | Manage billing, subscriptions, and payment methods |
| Organization | `org_admin`        | Full organization admin access                     |
| Settings     | `settings_read`    | View platform settings                             |

***

## Role Scope

Workspace roles can be **global** or **workspace-scoped**:

* **Global role** (`is_global=true`) — applies to every workspace the user belongs to.
* **Workspace-scoped role** — applies only to the specific workspace the role was created for.

Global roles are created from the **Roles → Workspace → All workspaces** view. Workspace-scoped roles are created for a specific workspace.

***

## Admin Configuration

Role-to-permission mapping and global authorization policy should be managed from **Settings → Roles** by users with `workspace_admin` (for workspace roles) or `org_admin` (for organization roles).

<Tip>
  Keep role definitions small and composable. Use the individual permission keys as the stable contract rather than building monolithic admin roles.
</Tip>