# Roles & Permissions

## Overview

This page controls platform-staff access — who on your team can log into the admin panel and what they are allowed to do there. Every capability is a named permission (for example `workspaces.suspend`), and a role is simply a bundle of permissions. A staff user is given one or more roles and inherits every permission those roles contain.

You'll find these two screens under Admin → Roles and Admin → Permissions. Assigning a role to an actual staff account happens on the User Management page.

> Platform vs. workspace. The roles here govern your own back-office staff. They are completely separate from the per-workspace roles (owner, admin, manager, agent, viewer) that your customers use to organize their own teams. See Platform roles vs. workspace roles below.

## The Pre-Seeded Platform Roles

A fresh install seeds six roles. Two are full-access administration roles, three are platform-operator roles for the SaaS team, and one is the baseline customer role. You can edit or delete any of them except Super Admin, which is system-locked.

Role | Scope | What it can do
--- | --- | ---
Super Admin | Platform | Every permission, always. System-locked — cannot be deleted, and is the only role allowed to pull the emergency brakes on the Security page. The installer promotes the first admin account to this role.
Admin | Platform | Also granted every permission, but not system-locked. Use this for trusted operators who run the platform day to day.
Manager | Platform | All `view` and `edit` permissions (plus `inbox.reply`, `inbox.assign`, `billing.invoices`, `audit.export`) — but no `create` or `delete`. A useful, non-destructive operator role.
Platform Support | Platform | Operate the SaaS without touching authorization or billing settings: view all workspaces, impersonate, flag/note, view the audit log, view all users. No role/permission management.
Auditor | Platform | Read-only across the platform for compliance reviews: view all workspaces, all conversations, the audit log, and all users. Cannot impersonate.
User | Baseline | Only the `*.view` permissions. The default low-privilege role.

> Note: Super Admin and Admin are tagged System roles in the list; everything you create is tagged Custom. The list page also surfaces a "Roles without users" counter so you can spot roles worth archiving.

## How Permissions Are Named

Every permission follows a simple `module.action` pattern, lowercase with no spaces. The part before the dot is the module (the area it covers); the part after is the action (what it allows). This is what lets the role editor group permissions neatly into per-module cards.

Pattern | Examples
--- | ---
Standard CRUD | `users.view`, `campaigns.create`, `templates.edit`, `flows.delete`
Module-specific actions | `campaigns.send`, `devices.pair`, `workspaces.suspend`, `billing.refund`, `metaads.approve`, `audit.export`, `users.login_as`
Platform-tier actions | `platform.workspace.view_all`, `platform.workspace.impersonate`, `platform.conversation.flag_spam`, `platform.note.write`, `platform.audit.view`

WaDesk ships permissions across these modules: `users`, `roles`, `permissions`, `workspaces`, `devices`, `packages`, `campaigns`, `metaads`, `templates`, `flows`, `webhooks`, `integrations`, `contacts`, `analytics`, `inbox`, `billing`, `audit`, `security`, `settings`, `support`, and the `platform.*` set used for cross-workspace operator tools.

> Note: The `platform.*` permissions are the ones that control the Platform Inbox and impersonation — they decide which staff can see and act across every customer workspace.

## Creating a Role

From Admin → Roles, click Add role and work through two steps:

1. Role details. Give the role a unique name (e.g. Sales Lead). Names must be unique across the platform. The Scope and "Start from template" selectors are convenience helpers for picking a starting set of boxes — what actually gets saved is the checkboxes in step 2.
2. Assign permissions. A matrix lists every permission grouped by module. Tick individual flags, use a row's Select all to grant a whole module at once, or the header Select all permissions to grant everything. A live counter shows how many of the total you have selected.

Click Create role in the top bar. The new role appears immediately in the list with its permission count and a progress bar showing how much of the full permission set it covers.

## Editing a Role & Assigning Permissions

Open any role from the list (row menu → Edit role) to rename it or change its permissions. The permission matrix arrives pre-checked to match the role's current grants; tick or untick boxes and click Save changes.

Saving performs a full sync: the role ends up with exactly the boxes that are ticked. Unticking a box revokes that capability from every staff user holding the role, and the change takes effect immediately because the permission cache is flushed on save.

The edit screen also has a Danger zone with shortcuts to duplicate the role, reassign its users to another role, and delete it.

> Revoking is instant and broad. Because a role is shared, removing a permission affects all users assigned to that role at once. Before unticking a sensitive flag (such as `billing.refund` or any `platform.*` permission), confirm who currently holds the role on the User Management page.

## Managing the Permission Catalog

Admin → Permissions is the master list of every permission the platform recognizes, grouped into per-module cards. The header stats show the total count, how many are attached to at least one role, and an orphan counter for permissions currently used by no roles.

### Add a permission

Click Add permission. Pick a module and type an action; the form assembles the `module.action` name for you and shows a live preview. You can also type a full custom name directly. Once created, the permission becomes available as a checkbox in the role editor — creating a permission does not grant it to anyone until you attach it to a role.

### Delete a permission

Each permission row has a Delete action that shows how many roles currently use it. There is intentionally no edit screen for permissions: renaming one that roles already use would silently detach every one of them, so the only operations are create and delete.

> Deleting a permission is immediate. Any role that referenced the flag loses that capability the moment you confirm. Prefer deleting only orphan permissions (shown in amber, attached to zero roles).

## Platform Roles vs. Workspace Roles

WaDesk has two completely independent permission systems. It is important not to confuse them.

| Platform roles (this page) | Workspace roles
--- | --- | ---
Who | Your back-office / SaaS staff | Your customers' own teammates
Roles | Super Admin, Admin, Manager, Platform Support, Auditor, User (and any custom role you add) | Owner, Admin, Manager, Agent, Viewer (a fixed five-rung hierarchy)
How it's scoped | Global — granted directly to the staff user, across the whole platform | Per workspace — the same person can be "Manager in Acme" and "Viewer in Globex"
Managed at | Admin → Roles and Admin → Permissions | The team members page inside each workspace
Editable | Yes — you define your own roles and fine-grained permissions | No — the five roles and their capabilities are fixed

For the full breakdown of the five per-workspace roles, who can grant which role, and how members are invited and removed, see Team Members & Roles in the Account & Team section.

> The bridge between the two: impersonation. A platform staffer with the `platform.workspace.impersonate` permission can temporarily view a customer workspace as its owner — see Platform Inbox & Impersonation. Everything else is firewalled: holding a platform role gives a staffer no standing inside any customer workspace.

## Best Practices

- Reserve Super Admin. Keep the count of Super Admin users as small as possible — it is the only role that can revoke all sessions, force password resets, rotate webhook secrets, and halt all sends.
- Hand out Platform Support, not Admin. For support staff who only need to triage and impersonate, the seeded Platform Support role is the right fit. It deliberately excludes role/permission management and billing.
- Use Auditor for external reviews. It is read-only and cannot impersonate, which makes it safe to hand to a compliance reviewer.
- Keep the catalog tidy. Watch the orphan-permission counter and prune flags no role uses.
- Everything is audited. Granting sensitive roles and impersonating workspaces are recorded in the audit log. Review it periodically.