Skip to main content

​
1. Concepts: Authorization, permissions, and roles in Zenskar

Zenskar uses a form of role-based access control (RBAC) for authorization. It helps to keep authorization distinct from authentication, since the two are easy to conflate: 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 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

​
Permission model

​
Default roles

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