Skip to content
User Guide

Settings → User Access → Roles

Roles are bundles of permissions that you assign to users. A user can have several roles; the effective permissions are the union across roles. MisterShell seeds built-in roles for common responsibilities. Built-in roles are read-only, but a role administrator can duplicate one and customize the copy.

Each role can also be scoped to a subset of locations, which restricts every action on resources to only those locations.

What you can do

  • Inspect and duplicate built-in roles.
  • Create, edit, duplicate, and delete custom roles.
  • Pick from the full list of application permissions.
  • Scope a role to specific locations.

Table columns

ColumnNotes
NameThe role’s display name.
DescriptionFree-text description.
PermissionsBadge with the count of permissions granted by this role.
TypeBuilt in for platform-managed roles, otherwise Custom.
Location ScopeAll locations if the role is workspace-wide, N locations for the number of explicitly stored scope roots, or Invalid scope if restriction is on but no location is selected.
ActionsView built-in roles; duplicate roles; edit or delete custom roles when permitted.

Common tasks

Create a role

  1. Click Create Role at the top right.
  2. Fill the form:
    • Name — a descriptive label (e.g., Infrastructure Engineer — EMEA, Auditor, Read-only).
    • Admin Rights — a toggle that makes this a full-administrator role with access to everything. Turning it on hides the permission matrix and the location pane: an admin role always applies globally.
    • Description — optional notes.
    • Permissions — a matrix with permission categories on rows and actions (read, write, delete, …) on columns; tick the cells the role should grant. A badge counts how many are selected, and the help icon next to each category explains what its permissions cover.
    • Location scope — leave Restrict by location unticked to grant across the whole workspace. Tick it, then select one or more scope roots. Every current and future descendant is inherited, and navigation ancestors are included without opening their other branches. Explicit selections use the primary color; inherited locations use the secondary color. A restricted role with no explicit selection fails validation.
  3. Click Create Role (or Save Changes when editing).

Edit a role

Built-in roles cannot be edited. Duplicate one first if you need a customized variant.

  1. Click the blue edit icon on a custom role.
  2. Update name, permissions, scope, or description.
  3. Click Save Changes.

Changes take effect immediately for every user who has the role. If a user currently holds a permission only because of a location-scoped role, removing that scope also removes the permission in that area.

Delete a role

Built-in roles cannot be deleted.

Roles referenced by team vault credentials cannot be deleted until those sharing references are removed. A member with access to the entry must change its sharing or delete it; role administration does not grant access to vault values. Approval controls, approval rules, unfinished runs, and pending requests can also block deletion. Resolve the dependencies reported by MisterShell before trying again.

  1. Click the red trash icon on a custom role.
  2. Confirm. The role is detached from every user; users who relied on that role for their only permission lose access.

Deletion is permanent. If in doubt, edit the role to remove all its permissions first and observe the effect.

Duplicate a role

  1. Click the duplicate icon on the role you want to use as a starting point.
  2. Review the generated copy name, permissions, and location scope.
  3. Click Create Role.

The duplicate is a normal custom role. Later built-in role synchronization does not change it. Duplicating a role that grants full administrator access requires full administrator access yourself.

Location scope rules

  • A role without location scope grants its permissions everywhere.
  • A role with location scope grants its permissions at every explicitly selected location and all of its current and future descendants.
  • Ancestors are visible only so the user can navigate from the root. Selecting /EMEA/France permits operations in /EMEA/France and France’s descendants; / and /EMEA are navigable but resources and actions there remain out of scope. /EMEA/Germany is not visible or accessible.
  • Selecting /EMEA automatically covers a /EMEA/Germany location added later; the role does not need to be edited.
  • Clicking an inherited location makes that exact location explicit. Removing an explicit selection removes only that stored root; it may remain inherited through another explicit root.
  • A user can combine a non-scoped role (e.g., Auditor) with a scoped role (e.g., Infrastructure Engineer — EMEA). The non-scoped role applies everywhere; the scoped role applies only at its selected locations and their descendants.

Permissions

  • Read: app.roles.read.
  • Create / edit: app.roles.write.
  • Delete: app.roles.delete.