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

# Roles and permissions

> How Pixwel determines who a user is and what they can do — group types, permissions, account types, and the roles derived from them.

<Info>
  For a plain-language overview aimed at end users, see [User roles](/features/user-roles). This page is the technical reference.
</Info>

Pixwel has no single `role` field on a user. Access is layered, and a user's effective role is the combination of three things:

1. **Group type** — the structural role, set by the kind of group a user belongs to (admin, studio department, regional contact, vendor).
2. **Permissions** — fine-grained `access` flags granted to a group, scoped by studio, project, territory, language, and usage.
3. **Account type** — whether the account is a full `member` or a limited `guest`.

On top of these, the app derives a few **functional roles** at runtime (for example "vendor" or "admin manager") from the permission flags, and a few **contextual roles** that only apply within a single work request.

<Note>
  Groups and permissions are managed by admins in the **Admin** area of the UI (Groups, Permissions, Studios, Territories tabs). That admin interface is the source of truth for everything on this page.
</Note>

## Group types

A user belongs to one or more groups, and each group has a `type`. The type defines the structural role and the org scope. Defined in `api/models/Groups.php` and surfaced in the UI in `ui/3x/constants/admin.js`.

| Type | Name              | Org scope                                      | Default permissions                       |
| ---- | ----------------- | ---------------------------------------------- | ----------------------------------------- |
| `a`  | Admin             | None — system-wide                             | All (`*`). There is only one admin group. |
| `sd` | Studio Department | One studio; no project or territory            | Sharing, download, orders, notes          |
| `rc` | Regional Contact  | One studio, one project, one territory         | Permission-based                          |
| `v`  | Vendor            | One or more studios, projects, and territories | Preview, download (sometimes)             |

A group also carries the `studios`, `territories`, and `users` it applies to, plus optional `domains` for auto-assigning users by email domain.

The API checks structural role by group membership:

```php theme={null}
// api/models/Users.php
$user->is(Groups::ADMIN);   // true if the user is in any group of type "a"
```

## Account types

Orthogonal to group type, every user is either a member or a guest. Defined in `api/models/Users.php`.

| Account type | Meaning                                                             |
| ------------ | ------------------------------------------------------------------- |
| `member`     | Full account. Must complete registration and approval. The default. |
| `guest`      | Limited account. Requires approval only, not full registration.     |

```php theme={null}
// api/models/Users.php
$user->isGuest();   // accountType === "guest"
$user->isMember();  // not a guest
```

Guests are heavily restricted in the UI — they see only Projects and Shares, and lose access to Work Requests, Downloads, the Order and Share queues, Notifications, and Preferences.

## Permissions

Group type sets the baseline, but capabilities come from **permission `access` flags** attached to a group. These are the named actions a user can perform. Labels are defined in `ui/3x/constants/admin.js` (`PERMISSION_ACTION_LABELS`); the schema lives in `api/models/Permissions.php`.

| Flag                   | Label                            | Grants                                               |
| ---------------------- | -------------------------------- | ---------------------------------------------------- |
| `previews`             | Previews                         | View asset previews (on by default)                  |
| `download`             | Download                         | Download files                                       |
| `sharing`              | Unrestricted Sharing             | Re-share without approval                            |
| `requests`             | Place Orders                     | Submit work requests                                 |
| `notes`                | Add/Edit Notes                   | Edit asset notes                                     |
| `autosubs`             | Automated Subtitles              | Order automated subtitles                            |
| `modifySubs`           | Modify Subtitles                 | Edit subtitles                                       |
| `social`               | Social Publish                   | Publish to social channels                           |
| `voting`               | Voting                           | Use the share voting feature                         |
| `ingest`               | Ingest Assets                    | Ingest new assets                                    |
| `manageWorkRequests`   | Manage Work Requests             | Fulfill and manage work requests (vendor capability) |
| `adminWorkRequests`    | Admin Work Requests              | Administer work requests across groups               |
| `projectAdminView`     | View Projects & Assets           | View the project admin                               |
| `projectAdminUpdate`   | Update Projects & Assets         | Make changes in the project admin                    |
| `projectAdminEmbargos` | Manage Embargoes                 | Set and lift embargoes                               |
| `privateAccess`        | Blanket Access to Private Assets | View private assets                                  |
| `workRequestReport`    | Reports: Work Requests           | View the work request report                         |
| `groupSpendingReport`  | Reports: Group Spending Summary  | View group spending                                  |
| `exceptionReport`      | Reports: Group Exceptions        | View group exceptions                                |
| `downloadReport`       | Reports: Downloads               | View the download report                             |
| `feedbackReport`       | Reports: Feedback                | View the feedback report                             |
| `encodeReport`         | Reports: Encodes                 | View the encode report                               |

Permission `access` is granted per group and can be **scoped** — by studio, project, and territory on the group, and by country, language, and [usage](/subtitler-dng-permissions) on the permission's `sources`. So "download" for one group can be narrower than "download" for another.

## Functional roles in the UI

The front end derives a handful of roles from the data above. These determine what menu items and screens a user sees (`ui/3x/modules/services/user-service.js`).

<Note>
  "Admin manager" and "vendor" are **not** group types — they are derived from permission flags, so a user in any group can hold them.
</Note>

| Role               | How it's determined                                   | What it unlocks                                                        |
| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| **Admin**          | Member of a group with `type === 'a'`                 | Everything, including the Admin area and user impersonation            |
| **Admin manager**  | Has the `adminWorkRequests` permission                | Administer work requests across groups                                 |
| **Vendor**         | Has the `manageWorkRequests` permission               | Work Requests and the Order Queue; fulfill orders                      |
| **Territory user** | Owns a work request, or shares a group with its owner | Acts on their own/their group's work requests                          |
| **Regular user**   | Authenticated, not admin and not vendor               | Projects and Shares, plus Downloads and Work Requests when not a guest |
| **Guest**          | `accountType === 'guest'`                             | Projects and Shares only                                               |

```javascript theme={null}
// ui/3x/modules/services/user-service.js
UserService.isAdmin(user);        // group.type === 'a'
UserService.isAdminManager(user); // permission.access.adminWorkRequests
UserService.isVendor(user);       // permission.access.manageWorkRequests
UserService.isGuest(user);        // accountType === 'guest'
```

## Work request roles

Within a single work request, a user takes on a **contextual role** that governs which status transitions they can drive. These are computed per request in `api/models/WorkRequests.php` and don't change the user's overall role.

| Role           | Who                                                            | Typical capability                            |
| -------------- | -------------------------------------------------------------- | --------------------------------------------- |
| **Admin**      | In the admin group, or granted admin on the request            | Drive most status transitions                 |
| **Manager**    | Group has `manageWorkRequests` on the request's studio/project | Manage the request, with some approval limits |
| **Owner**      | Created the request, or shares a group with the creator        | Submit and cancel; cannot force status        |
| **Translator** | Assigned as the request's translator (text or graphics)        | Update translation work                       |

## How roles map to the org structure

Roles are always relative to the organizational hierarchy:

* **Studios** are the top-level org unit. Studio departments, regional contacts, and vendors all attach to one or more studios.
* **Territories** are regional units (with their own languages). Groups are permissioned per territory, and permissions can be filtered by country and language.
* **Groups** tie it together: a group's `type` is the role, its `studios`/`territories` are the scope, its `users` are the members, and its permissions are the capabilities.