Permission catalog

Permissions are fine-grained capabilities stored on roles. System Admin has full access (*). Other roles list specific keys.

You do not need to memorize this page. Use it when you extend a role and wonder what a checkbox means, or when someone asks “why can’t I see Billing?”

For a shorter overview, see Permissions. For assigning roles, see Users & roles.

Screenshot needed

Custom role editor with permission checkboxes grouped by module.

Where: Manage users / roles → edit role

Save as: src/assets/screenshots/42-permission-catalog-ui.png

How permissions work

Idea	Meaning
Permission key	Stable string such as `projects.read`
Role	Named bundle of keys (Admin, Agent, Supervisor, or custom)
*``**	Grants everything — reserved for system Admin
Missing key	UI hides or blocks the action; API returns 403

Permissions are organization-wide capabilities. They do not replace project membership rules where those exist, and they do not bypass plan limits.

Projects

Permission	Allows	When you need it
`projects.read`	View projects and open project workspaces	Almost everyone who works in CXGear
`projects.write`	Create and edit projects	Admins and campaign owners

Without projects.read, the product is largely empty. Without projects.write, users can operate inside existing projects (if other permissions allow) but cannot create new ones.

Spinners

Permission	Allows	When you need it
`spinners.read`	View spinner definitions	Supervisors reviewing pipelines
`spinners.write`	Create and edit spinners	Builders and admins
`spinners.run`	Run / trigger spinners (including starting jobs)	Anyone who must launch outreach

A common pattern: supervisors get read + run, while only a smaller builder group gets write.

Integrations & vault

Permission	Allows	When you need it
`integrations.read`	View integrations (channels, AI providers, …)	Supervisors who need visibility
`integrations.write`	Create and change integrations	Admins connecting WhatsApp, LLMs, etc.
`vault.read`	View vault entries (secrets are masked)	Auditing which secrets exist
`vault.write`	Add or update secrets	Admins managing credentials

Prefer Integrations for LLM keys. Use Vault when a step needs a named secret. Treat both as sensitive — write is high privilege.

Dialler & conversations

Permission	Allows	When you need it
`dialler.access`	Dialler admin (lists, routing, desk tools)	Supervisors and dialler admins
`dialler.agent`	Take live voice calls	Desk agents with presence
`conversations.agent`	Receive and reply to chat sessions	Chat agents
`conversations.supervise`	Monitor, transfer, and supervise chats	Chat supervisors

Desk agents usually need agent permissions, not full Admin. Supervisors often combine dialler access with analytics read.

Analytics & Call Analyzer (PCA)

Permission	Allows	When you need it
`analytics.read`	View analytics dashboards	Supervisors and leads
`pca.setup`	Configure Post Call Analyzer setup	PCA admins
`pca.tags`	Manage analyzer tags	QA / PCA configuration
`pca.qa`	Manage QA scorecard	QA leads

Split PCA permissions when one team configures intake and another owns the scorecard.

Admin

Permission	Allows	When you need it
`users.manage`	Invite and manage users	Org admins
`roles.manage`	Create and edit custom roles	Org admins designing access
`data_tables.delete`	Delete data tables	Admins only — destructive

data_tables.delete is intentionally separate so builders can import data without permission to destroy tables.

Billing & developer

Permission	Allows	When you need it
`billing.read`	View billing, plans, and usage meters	Finance-aware admins
`api_keys.manage`	Create and revoke organization API keys	Developers and admins integrating CRMs

Developers who only manage webhooks may need api_keys.manage without full Admin — still treat keys as production secrets.

Practical role recipes

Role intent	Typical permissions
Desk agent	`projects.read`, `dialler.agent`, maybe `conversations.agent`
Supervisor	`projects.read`, `spinners.read`, `spinners.run`, `dialler.access`, `analytics.read`, conversations supervise as needed
Builder	`projects.read`, `spinners.*`, `integrations.read`
Org admin	`*` or broad write + `users.manage` + `roles.manage` + `billing.read`
Integrator	`api_keys.manage`, `projects.read`, `spinners.read`

Success looks like

Agents cannot open Billing or delete tables
Builders can publish spinners without managing users
Integrators can create API keys without full Admin
Custom roles are documented for your team’s onboarding

Common problems

Problem	Likely cause	What to do
“Button missing”	Permission not on role	Add the key or use a system role
Can see UI but API 403	Role changed after login	Sign out and back in
PLAN_LIMIT despite Admin	Plan meter, not permission	Open Billing
Over-privileged agents	Copied Admin role	Start from Agent and add only what is needed