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

# Manage roles

> Control user access and permissions with system and custom roles.

Roles define what users can do in Qwoty — which objects they can read, write, or delete, which settings they can manage, and which app-level actions they can perform. You assign one role to each user to control their permissions across the platform.

<Note>
  You must have the **Admin** role to view, create, or modify roles.
</Note>

## System roles

Qwoty provides four predefined system roles that cover the most common permission levels. You cannot edit or delete system roles.

* **Admin** — Full access to all workspaces, settings, and configuration. Can manage users, roles, templates, catalogs, and all system features.
* **Manager** — Access to the entire workspace. Can approve quotes, view reports, and manage team activities.
* **Sales Rep** — Can create and manage quotes, customers, and Dealrooms. No access to system settings or team-wide reports.
* **Viewer** — Read-only access. Can view quotes and data but cannot create or edit anything.

<Info>
  The API name for **Sales Rep** is `Sale` for backwards compatibility with earlier versions.
</Info>

## Custom roles

You can create custom roles to define granular permissions that match your organization's needs. Custom roles appear with a **Custom** badge in the roles list and can be edited or deleted at any time.

Use custom roles to:

* Grant partial access to specific modules (for example, catalogs only, or reports only)
* Restrict actions on an object family (for example, read customers but never delete)
* Scope project visibility by team, business unit, or workspace
* Enable or disable transversal actions like CSV imports and exports

## The permission model

A Qwoty role configures permissions across three distinct areas.

### Objects — CRUD per object family

The **Objects** section controls what users can read, write, or delete, broken down by object family. You set one checkbox per action per family.

| Object family          | Objects concerned                | Actions               |
| ---------------------- | -------------------------------- | --------------------- |
| **Project**            | Quote, contract, order           | Read / Write / Delete |
| **Products & Pricing** | Catalogs, Products, price grid   | Read / Write / Delete |
| **Customers**          | Customers                        | Read / Write / Delete |
| **Workflow**           | Approval, workflow, configurator | Read / Write / Delete |
| **Content**            | Contract model, media, content   | Read / Write / Delete |
| **Templates**          | Project templates                | Read / Write / Delete |

<Tip>
  Grant **Read** without **Write** to give users visibility without letting them change records — useful for Finance or Executive roles.
</Tip>

### Project Access Level

At the top of the **Objects** section, the **Project Access Level** dropdown controls the scope of projects a user can see, regardless of their Read/Write/Delete rights.

* **Workspace** — The user can access projects across the entire workspace
* **Team** — The user only accesses projects created by their team
* **Personal** — The user only accesses projects they created themselves

<Warning>
  Project Access Level acts as a filter on top of CRUD rights. A user with `Project: Read` set to true but a `Personal` access level will only see their own quotes, even if the workspace contains thousands.
</Warning>

### Settings — toggle per admin area

The **Settings** section controls access to administration zones. Each zone has a single **Authorize** toggle.

| Setting          | What it unlocks                             |
| ---------------- | ------------------------------------------- |
| **Workspace**    | Set global workspace preferences            |
| **User & Teams** | Add or remove users and define teams        |
| **Roles**        | Define user roles and access levels         |
| **Data**         | Edit CPQ data structure and fields          |
| **Developers**   | Manage integrations, API keys, and webhooks |
| **Organization** | Manage multi-tenant org and billing         |

<Note>
  Settings access is binary — a user either has full access to a zone or none. If you need finer control, keep the zone off and delegate configuration to an Admin.
</Note>

### Apps — transversal app-level actions

The **Apps** section controls transversal capabilities that apply across modules.

| Action                         | Description                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| **Import CSV**                 | Allow importing data from CSV files                                                   |
| **Export CSV**                 | Allow exporting data to CSV files                                                     |
| **Overpass sales restriction** | Allow bypassing restrictions such as approvals, discount caps, and pricing guardrails |

<Warning>
  **Overpass sales restriction** gives users the ability to skip approval workflows and discount limits. Grant this only to senior roles — typically VP Sales, CRO, or equivalent.
</Warning>

## How roles work with teams

Roles define **what** users can do. Teams define **which resources** they can access. The Project Access Level in a role connects the two.

| Element                  | Controls                   | Example                                           |
| ------------------------ | -------------------------- | ------------------------------------------------- |
| **Role**                 | Feature access and actions | A Sales Rep can write quotes; a Viewer cannot     |
| **Team**                 | Group of users             | A Sales Rep belongs to the France team            |
| **Project Access Level** | Scope of visible projects  | `Team` limits the Sales Rep to France team quotes |

When you assign a user to a team and set their role's Project Access Level to `Team`, they only see resources scoped to that team. Change it to `Workspace` and they see everything.

<Warning>
  If you remove a user from all teams, they lose access to templates, catalogs, and team-scoped projects, even if they retain their role.
</Warning>

## Access the roles screen

<Steps>
  <Step title="Open Settings">
    In the left sidebar, click **Settings**.
  </Step>

  <Step title="Navigate to Role">
    Under the **Users & Team** section, click **Role** to view the list of all available roles.
  </Step>
</Steps>

## View the roles list

The roles table displays:

* **Role** — The role name
* **API name** — Technical identifier used for integrations and API calls
* **Type** — **System** (green badge) or **Custom** (gray badge)

Use the search bar to filter roles by name or API name. You can adjust the number of rows displayed per page and navigate between pages using the pagination controls at the bottom.

## Create a new role

<Steps>
  <Step title="Click New role">
    Click the **+ New role** button at the top right of the screen.
  </Step>

  <Step title="Set the role identity">
    Enter the role **name** and **API name**. The API name cannot contain spaces or special characters.
  </Step>

  <Step title="Configure object permissions">
    Select the **Project Access Level** (Workspace, Team, or Personal), then check the **Read**, **Write**, and **Delete** boxes for each object family.
  </Step>

  <Step title="Configure settings access">
    Toggle **Authorize** on each setting zone the role should manage (Workspace, Users & Teams, Roles, Data, Developers, Organization).
  </Step>

  <Step title="Configure app-level actions">
    Toggle **Authorize** on each app-level action the role should perform (Import CSV, Export CSV, Overpass sales restriction).
  </Step>

  <Step title="Save">
    Click **Save**. The role appears in the list with a **Custom** badge.
  </Step>
</Steps>

## View a system role

<Steps>
  <Step title="Locate the role">
    Find the system role in the roles list.
  </Step>

  <Step title="Open the menu">
    Click the **⋮** menu to the right of the row.
  </Step>

  <Step title="Select View">
    Click **View** to open the role details in read-only mode.
  </Step>
</Steps>

## Edit a custom role

<Steps>
  <Step title="Locate the role">
    Find the custom role in the roles list.
  </Step>

  <Step title="Open the menu">
    Click the **⋮** menu to the right of the row.
  </Step>

  <Step title="Select Edit">
    Click **Edit**, update the Objects, Settings, or Apps sections, then click **Save**.
  </Step>
</Steps>

## Delete a custom role

<Steps>
  <Step title="Locate the role">
    Find the custom role in the roles list.
  </Step>

  <Step title="Open the menu">
    Click the **⋮** menu to the right of the row.
  </Step>

  <Step title="Select Delete">
    Click **Delete** and confirm the deletion.
  </Step>
</Steps>

<Warning>
  Before deleting a custom role, reassign any users currently holding it. Users with a deleted role lose access until they receive a new role.
</Warning>

## Assign a role to a user

You assign a role when you invite a new user or edit an existing one.

<Steps>
  <Step title="Navigate to user management">
    Click **Settings** in the left sidebar, then click **User** under the **Users & Team** section.
  </Step>

  <Step title="Select the user">
    To invite a new user, click **+ Invite user**. To edit an existing user, click the **⋮** menu next to their name and select **Edit**.
  </Step>

  <Step title="Choose the role">
    In the user form, select the appropriate role from the **Role** dropdown menu.
  </Step>

  <Step title="Save your changes">
    Click **Save** or **Send invitation** to apply the role.
  </Step>
</Steps>

<Tip>
  Assign the **Manager** role to users who need to approve quotes but don't require full Admin privileges.
</Tip>

## Common questions

<AccordionGroup>
  <Accordion title="Can I modify a system role?">
    No. System roles are locked to ensure Qwoty functions correctly. Create a custom role instead and configure the permissions to match your needs.
  </Accordion>

  <Accordion title="What happens if I delete a custom role assigned to users?">
    The role is removed, but users assigned to it remain in the system. You must manually reassign each user to a new role before they can access Qwoty again.
  </Accordion>

  <Accordion title="Can a user have multiple roles?">
    No. Each user is assigned exactly one role. If you need a combination of permissions, create a custom role that bundles them.
  </Accordion>

  <Accordion title="What is the API name used for?">
    The API name is a technical identifier used in integrations, API calls, and automation scripts. It cannot contain spaces or special characters.
  </Accordion>

  <Accordion title="Do roles affect API access?">
    Yes. API requests authenticate using user credentials or API keys tied to a user account, so role permissions apply to API calls as well.
  </Accordion>

  <Accordion title="What happens when I change a user's role?">
    The change takes effect immediately. The user's permissions update the next time they refresh their session or log in again.
  </Accordion>

  <Accordion title="What's the difference between Project Access Level and Read permission?">
    Read permission decides **whether** a user can view quotes, contracts, and orders. Project Access Level decides **which** ones — all projects in the workspace, only their team's, or only those they created themselves. Both must align for a user to see a project.
  </Accordion>

  <Accordion title="Why would I grant Overpass sales restriction?">
    Grant this only to senior roles who legitimately need to bypass approval workflows, discount caps, or pricing guardrails — typically VP Sales, CRO, or Finance leads handling exceptions.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Manage users" icon="users" href="/user-guide/settings/users/manage-users">
    View, invite, and edit users in your workspace.
  </Card>

  <Card title="Manage teams" icon="user-group" href="/user-guide/settings/users/manage-teams">
    Organize users into teams to control access to templates and catalogs.
  </Card>

  <Card title="Workspace settings" icon="building" href="/user-guide/settings/workspace/general">
    Configure workspace-level settings and business units.
  </Card>

  <Card title="Approvals & workflows" icon="circle-check" href="/user-guide/workflows/introduction">
    Set up approval rules that depend on roles and team scope.
  </Card>
</CardGroup>