> ## Documentation Index
> Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Roles
## 1. Concepts: Authorization, permissions, and roles in Zenskar
Zenskar uses a form of [role-based access control (RBAC)](https://auth0.com/docs/manage-users/access-control/rbac) for **authorization**. It helps to keep authorization distinct from authentication, since the two are easy to conflate:
| Authentication | Authorization |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Are you who you claim to be? | Are you allowed to do what you are trying to do? |
| Verified through credentials such as a password, a single sign-on provider, or two-factor authentication. | Granted through policies and rules, in Zenskar's case roles and permissions, set up by an administrator. |
| Governed by protocols such as OpenID Connect (OIDC). | Governed by frameworks such as OAuth 2.0. |
Every action inside Zenskar is protected by both: you first prove who you are, then Zenskar checks whether your assigned role and any additional permissions allow the specific action you are trying to take.
### What a role is
A **role** is a named collection of permissions. Rather than granting permissions to people one at a time, you grant permissions to a role, then assign that role to a user. This keeps access consistent across your organization: everyone with the same role has the same baseline access, and updating the role's permissions immediately updates access for every user assigned to it. A role is assigned to exactly one user at a time, but the same role can be assigned to as many users as you like.
### The permission catalog
Zenskar's permissions are organized by **module**, where a module corresponds to an area of the product, for example Customers, Contracts, Invoices, Products, Business Entities, Tax Categories, Accounting, Revenue Recognition, Reports, Integrations, Webhooks, API Keys, and many more. There are 54 resource modules in total.
For most modules, four base permissions are available:
* **Read**: view records in that module.
* **Create**: create new records in that module.
* **Update**: edit existing records in that module.
* **Delete**: delete records in that module.
Create and Update are separate permissions. This means a role can grant the ability to create new records in a module without also granting the ability to edit existing ones, or the other way around. Plan your custom roles with this distinction in mind, since a role that looks like it grants full write access may only grant one half of it.
A small number of modules, especially invoices, have a few extra, more specific permissions beyond the standard four, such as the ability to approve an invoice. These extra permissions appear alongside the standard four wherever they exist, grouped under the same module.
In the role's permission picker, permissions are grouped by module, shown as an uppercase section header, with a search box above the list. You grant permissions by moving them from an **Available** list into a **Granted** list, and revoke them by moving them back.
### Default roles
Every new organization is seeded automatically with two built-in roles:
* **admin**: has every available permission across every module.
* **user**: has read-only access, the Read permission, across every module.
Unlike some systems, these default roles are not protected. An administrator can rename them, change their permissions, or delete them, exactly like any custom role. Be careful when editing the admin or user role: removing permissions from admin, or adding write permissions to user, changes access for everyone assigned to that role, and could unintentionally weaken or lock people out of your organization's default access levels.
***
## 2. Walkthrough: Create a narrow custom role and assign it to a user
This walkthrough creates a "Billing viewer" role that can only view invoices and customers, then assigns it to a teammate.
1. Click the account menu at the bottom of the left sidebar, then click **Roles**.
2. Click **Add New Role**.
3. Enter `Billing viewer` as the **Name**.
4. In the permission picker, use the search box to find the **Invoices** module, and move its **Read** permission from **Available** to **Granted**.
5. Search for the **Customers** module, and move its **Read** permission from **Available** to **Granted** as well.
6. Click **Add Role**. The new role now appears in the roles list with these two permissions and nothing else.
7. To assign it to a teammate, go to the **Users** page and either add a new user with this role or edit an existing user's **Role** field. See [Users](/docs/20260301/security/role-based-access-control/users) for the full walkthrough.
***
## 3. How-to guides
### Create a role
1. Click the account menu at the bottom of the left sidebar, then click **Roles**.
2. Click **Add New Role**.
3. Enter a **Name**.
4. Use the search box to find each module you need, and move the relevant permissions from **Available** to **Granted**.
5. Click **Add Role**.
Granting every available permission gives whoever holds that role unrestricted access to your organization. Use this only for roles that genuinely need it.
### Edit a role's permissions
1. On the **Roles** page, click the role you want to edit.
2. Add or remove permissions using the **Available** and **Granted** lists.
3. Click **Update Role**.
Changes take effect immediately for every user currently assigned to the role.
### Find a specific permission in the picker
Permissions are grouped by module, with the module name shown as an uppercase header above its permissions. Use the search box above the **Available** and **Granted** lists to filter by permission or module name instead of scrolling through all 54 modules.
### Delete a role
1. On the **Roles** page, open the kebab menu on the role's row.
2. Click **Delete**.
3. Confirm the deletion.
Attempting to delete a role that still has users assigned to it will fail. Reassign those users to a different role first, then delete the role.
***
## 4. Reference
### Location
Click the account menu (your name or avatar) at the bottom of the left sidebar, then click **Roles**. The same menu also lists **Users**, **Settings**, and **Logout**.
### Fields
| Field | Required | Notes |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| Name | Yes | The role's display name |
| Grant Permissions | No | Dual-list picker: move permissions between **Available** and **Granted**, grouped by module, with a search box |
### Permission model
| Aspect | Detail |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Permission format | `can_{verb}_{module}`, for example `can_read_invoice` |
| Base verbs | Read, Create, Update, Delete |
| Resource modules | 54, covering areas such as customers, contracts, products, invoices, credit notes, payments, payment methods, entitlements, tax categories, accounting, revenue recognition, reports, integrations, webhooks, segments, alerts, API keys, and SAML |
| Extra module-specific verbs | A small number of modules, especially invoices, add a few extra permissions beyond the base four, such as the ability to approve an invoice |
| Grouping in the UI | By module, shown as an uppercase section header, with a search box |
### Default roles
| Role | Grants | Editable? |
| ----- | ------------------------------------ | ----------------------------------------------------------- |
| admin | Every permission across every module | Yes. Can be renamed, edited, or deleted like any other role |
| user | Read on every module | Yes. Can be renamed, edited, or deleted like any other role |
Because the default roles are editable and deletable, double-check any change to admin or user before saving it. There is no separate protected or hidden role to fall back on if these are altered unintentionally.
### Role deletion rules
| Situation | Behavior |
| ----------------------------------------------------- | ---------------------------------------------------- |
| Deleting a role with no users assigned | Succeeds. The role is removed |
| Deleting a role with one or more users still assigned | Fails. Reassign every user to a different role first |