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

# Roles & Permissions

> The three system roles, how custom roles are built from the Create/Read/Update/Delete matrix, and the guard rails that refuse a change.

export const Screenshot = ({id, alt, caption, frame = 'browser', url, marks = [], lang = 'en', workspace = 'northwind-outbound'}) => {
  const src = `/images/screenshots/${lang}/${id}.png`;
  const chrome = url ? `app.pipelime.ai/${workspace}${url}` : 'app.pipelime.ai';
  return <figure className={`pl-shot pl-shot--${frame} not-prose`}>
      <div className="pl-shot__frame">
        {frame !== 'bare' && <div className="pl-shot__bar">
            <span className="pl-shot__dots">
              <span className="pl-shot__dot" />
              <span className="pl-shot__dot" />
              <span className="pl-shot__dot" />
            </span>
            <span className="pl-shot__url">{chrome}</span>
          </div>}
        <div className="pl-shot__media">
          <img src={src} alt={alt} loading="lazy" />
          {marks.map(mark => <span key={mark.n} className="pl-shot__mark" style={{
    left: `${mark.x}%`,
    top: `${mark.y}%`
  }} aria-hidden="true">
              {mark.n}
            </span>)}
        </div>
      </div>
      {caption && <figcaption className="pl-shot__caption">{caption}</figcaption>}
    </figure>;
};

A role decides what a teammate can see and change in this workspace. Every workspace starts with the same three (Admin,
Member and Viewer) and you build any others yourself, by ticking boxes in a Create/Read/Update/Delete grid.

<div className="pl-availability">
  <div className="pl-availability__row">
    <div className="pl-availability__label">Where</div>
    <div className="pl-availability__value"><span className="pl-path">Settings<span className="pl-path__sep">→</span>Roles & Permissions</span></div>
  </div>

  <div className="pl-availability__row">
    <div className="pl-availability__label">Your role needs</div>
    <div className="pl-availability__value">Read access to Roles & Permissions <code>read-roles</code>. Admin have it by default.</div>
  </div>

  <div className="pl-availability__note">If you cannot find this in your sidebar, your workspace may have a custom menu configuration. Contact support and we will check it for you.</div>
</div>

Three system roles and one custom role look like this:

<Screenshot id="settings-team/roles-and-permissions--list" url="/settings/roles" alt="The Roles & Permissions table with four rows: Admin, Member and Viewer each carrying a System chip and a single view icon, followed by one custom role with a Custom chip, 1 in the Members column, an edit icon and a greyed-out delete icon" caption="A custom role's delete icon disables itself the moment a member holds it (1). The server refuses that delete as well, so moving those members onto another role is the only way through." marks={[{ n: 1, x: 90, y: 66 }]} />

## How it behaves

### The three system roles are shared, and nobody edits them

Admin, Member and Viewer are shared definitions, attached to your workspace rather than built for it: one Admin, one
Member, one Viewer, the same three grids in every workspace on the product. That is why none of them can be edited or
deleted. Opening one shows its grid for reference, with every checkbox disabled and a **Duplicate as custom role** button
in the footer where **Save** would be. The refusal is not only on screen: the server rejects an edit or a delete of a
system role for everyone, our own staff included.

<Screenshot id="settings-team/roles-and-permissions--system-role" url="/settings/roles" alt="The role editor dialog open read-only on the Admin role, titled Role details, with a blue info alert reading System roles can't be edited, Duplicate it to customise, above a Create/Read/Update/Delete grid of disabled checkboxes, and a Duplicate as custom role button in the footer" caption="A representative example: the module list here is shortened so the grid fits one image, but the alert, the disabled grid and the footer buttons are what every system role opens with." />

Member and Viewer are seeded with read access to the workspace itself, the teammate list and the subscription balance so
the app can load for them at all: a floor underneath whatever else either role holds.

A fourth system role exists above these three, for our own staff. It belongs to no workspace, it is never listed on this
screen, and nothing in the product can assign it to anyone in yours.

### Roles are ranked, and the ranking does one thing

The three system roles are ranked against each other (Admin over Member, Member over Viewer) and every custom role you
build ranks below all three. That ranking is used in exactly one place: removing a teammate from the workspace requires
your own role to rank at or above theirs. So a custom role you gave delete access to teammates still cannot remove
someone holding Admin, Member or Viewer.

### Duplicating carries the grid across

**Duplicate as custom role** switches the same dialog into create mode (the title changes to **Create role**) and
pre-fills the name field with the system role's own name followed by `(copy)`. The permission grid is not reset. Whatever
the system role held is still ticked, so duplicating Member and unticking a handful of rows is quicker than building a
role from nothing.

<Warning>
  Duplicating **Admin** is the exception. Admin holds impersonation permissions that no workspace role is ever allowed
  to hold, so they are not drawn in the grid. But they are still carried into the duplicate, invisibly, and saving is
  refused because of them. Unticking rows does not clear them, and reopening the dialog brings them back. Close it and
  start from **Create role** instead.
</Warning>

### A custom role is a name, a description and a grid

Creating or editing a custom role asks for a **Role name** (required), an optional **Description**, and the same
**Create** / **Read** / **Update** / **Delete** grid the system roles show, one row per module: campaigns, leads, email
accounts, workflows and so on. A module that grants fewer than four actions shows a dash in the columns it has nothing to
offer. The checkbox beside a module's own name toggles every action it has at once, and sits in a half-ticked state
while only some of them are on.

That grid is not this page's to define. It is the same catalogue for every workspace and every editor, and the full list
(with what each module grants and which system role already holds it) is on the [permission
catalogue](/en/reference/permissions-catalogue). Your browser caches it for a few minutes before asking again, since it
only changes when the product does.

Leaving every box unticked is refused before the request goes out: a role has to grant at least one permission.

### Saving is checked on the server

The grid you see is not filtered to what you personally hold. Everyone editing a role sees the same catalogue.
Overreach is caught on save instead, and the message names exactly what went wrong:

* *A reserved or already-taken name.* A short list of names is off-limits, the system roles among them, and no two custom
  roles in one workspace may share a name. Names are compared after being reduced to lowercase and hyphens, so
  "Campaign Manager" and "campaign-manager" count as the same name.
* *A permission outside the catalogue.* Impersonation permissions can never be granted to a workspace role, whatever the
  grid contains.
* *A permission you do not hold yourself.* You can only grant what your own role already grants you, so an editor with a
  narrower grid than Admin cannot hand out more than they have.

Each of those comes back as a plain sentence naming the offending name or permissions, shown exactly as the server wrote
it rather than replaced with generic copy. A successful save shows a **Role saved** toast.

If the role you just edited is the one you hold, the app refreshes your session straight away, so your sidebar and every
permission-gated control follow the new grid without a reload.

### Deleting is blocked while anyone still holds the role

A custom role's delete icon disables itself the instant its member count is above zero, with a tooltip naming how many
members are holding it: the greyed-out icon marked (1) above. That is a courtesy, not the guard: the server counts the
assignments again and refuses the delete for the same reason, and its refusal appears inside the confirmation dialog
rather than as a toast. Reassign those members first.

Confirming a delete on a role nobody holds asks once more, by name, before it goes. System roles have no delete icon at
all; a **View** icon is the only action on their row. The edit and delete icons on a custom role are themselves gated.
A role that can open this screen but holds no update or delete permission on roles sees the rows and no icons.

### Neither Member nor Viewer holds anything on roles

Member and Viewer hold no permission on the roles module at all, not even read. That is unlike almost everywhere else
in the product: Viewer can read campaigns, leads, email accounts, workflows and nearly every other module, and this is
the one place it has nothing.

A custom role behaves the same way if you did not tick the roles row when you built it. The same denial appears twice
below: first a custom role, then the system Viewer:

<Screenshot id="settings-team/roles-and-permissions--as-member" url="/settings/roles" alt="Settings for a teammate on a custom role with no roles permission. The Roles & Permissions tab is missing from the sidebar, and the settings area has opened a different tab instead" caption="The tab is not in your Settings at all, and the URL redirects to the first settings tab you can open." />

<Screenshot id="settings-team/roles-and-permissions--as-viewer" url="/settings/roles" alt="Settings for a read-only teammate on the system Viewer role. Roles & Permissions is still missing from the sidebar, the same as the custom role above" caption="Viewer reads almost every other module in the workspace. This is the exception, and it redirects the same way." />

Two different permissions are at work here, and they diverge on the Access tab rather than on this one. The role
*list* loads for anyone holding read access to roles, or update or create access to teammates. Someone who can invite
people or change their role needs the list to fill the role picker, even though they cannot open this screen. The
permission *catalogue* behind the grid loads only for read access to roles.

Elsewhere in the product, a control your role cannot use is usually not drawn at all. The button is gone rather than
greyed out. A few that anchor a layout stay visible and inert, with a tooltip explaining why. Roles & Permissions is
neither: the route itself sends you somewhere else.

<Note>
  A session cached from before permissions shipped is allowed everything until it refreshes, which is why none of this is
  the real guard. Hiding and disabling controls is presentation; the server authorises every request on its own.
</Note>

## Limits

|                              |                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| System roles                 | Admin, Member and Viewer, shared across every workspace, never editable, never deletable             |
| Editing a system role        | Not possible, for anyone. **Duplicate as custom role** copies its grid into a new one you can change |
| Custom roles                 | As many as you need. All rank below every system role, and no two may share a name in one workspace  |
| Role name                    | Required. The field stops at 50 characters                                                           |
| Description                  | Optional. The field stops at 255 characters                                                          |
| Permissions a role can grant | Only what the catalogue offers, and never more than the editor holds themselves                      |
| Never grantable              | Impersonation permissions, for any role in any workspace                                             |
| Deleting a role              | Blocked, on screen and on the server, while any member still holds it                                |
| Who can open this screen     | Anyone holding read access to roles. Member and Viewer hold no roles permission at all               |

## Related

<CardGroup cols={2}>
  <Card title="Permissions reference" icon="table" href="/en/settings-team/permissions-reference">
    The full grid module by module, with what each system role holds out of the box.
  </Card>

  <Card title="Invite team members and manage access" icon="users" href="/en/settings-team/invite-team-members">
    Send the invite, pick the role, and change it later from the Access tab, not from here.
  </Card>

  <Card title="Permission catalogue" icon="shield-check" href="/en/reference/permissions-catalogue">
    Every grantable permission on its own page, generated from the same catalogue this screen reads.
  </Card>
</CardGroup>