Permissions

Polygent uses a role-based permission system with a permission matrix, workspace membership, and admin bypass. Permissions cover sessions, workspaces, tickets, bots, planner, automations, memory, round tables, statistics, hosts, and more.

How permissions work

Two layers control access:

1. Permission categories — what you're allowed to do (e.g., tickets.manage)
2. Workspace membership — which workspaces you can act in

A non-admin user must hold the matching permission and be assigned to the workspace to access workspace-scoped resources.

Layer	Without it
Permission missing	UI hides the action; API returns 403
Workspace not assigned	Workspace and its data are invisible

Admin bypass

Users with the admin permission bypass all checks — they see every workspace and can perform every action regardless of explicit role grants. The sessions.manage_all permission also bypasses session ownership checks specifically.

First user auto-admin

The first user to sign in is automatically promoted to Admin. This avoids the chicken-and-egg problem of needing an admin to grant the first admin role.

Permission categories

Permissions are organized by area:

Cross-cutting

• admin — full system access
• users.view, users.manage
• settings.view, settings.manage
• statistics.view

Sessions

• sessions.view_own, sessions.view_all
• sessions.create, sessions.edit, sessions.delete
• sessions.manage_all
• sessions.merge_to_starter

Workspaces

• workspaces.view, workspaces.create, workspaces.edit
• workspaces.delete, workspaces.users

Tickets

• tickets.view, tickets.manage
• tickets.approve_dev, tickets.approve_qa
• tickets.skip_to_merge

Hosts and deployment

• hosts.view, hosts.manage
• hosts.manage_api_keys

Workflows and bots

• workflows.view, workflows.manage
• bots.view, bots.manage

Subagents

• subagents.view, subagents.manage

MCP servers

• mcps.view, mcps.manage

Planner

• planner.create, planner.view_all, planner.manage

Automations

• automations.view_own, automations.view_all
• automations.manage, automations.manage_all

Insights

• insights.view, insights.manage

Memory

• memory.view, memory.manage

Merge conflicts

• merge_conflicts.view, merge_conflicts.manage

Round tables

• roundtables.create, roundtables.manage_personas

Role management

Permissions are bundled into roles. The Roles page lets you:

• Create Role — name a new role
• Edit Role Permissions — toggle individual permissions in a matrix UI
• Delete Role — only if no users are assigned
• Permission Matrix Editor — visual grid of every role × every permission

Out of the box, only the Admin role exists (holding all permissions, auto-assigned to the first user to sign in). Create the roles your team needs on top of it — common starting points are:

• Admin — all permissions (seeded)
• Member — standard team access (view + manage own resources)
• Viewer — read-only across the platform

User role assignment

Each user is assigned one or more roles. The user's effective permissions are the union of their role permissions plus any direct grants.

Workspace assignment vs. permissions

What it controls	Where to set it
What the user can do	Role → Permission
Which workspaces the user can act on	Workspace → Members

A user with tickets.manage who isn't a member of Workspace A can manage tickets in other workspaces, but Workspace A is invisible to them.

Examples

A QA reviewer role Create a QA role with sessions.view_all, tickets.view, tickets.approve_qa, and statistics.view. Assign it to your testers and add them to the workspaces they cover. They can review and approve/reject QA on tickets, watch sessions, and see dashboards — but cannot create workspaces, manage bots, or change settings.

A developer role Create a Developer role with sessions.create/sessions.edit/sessions.view_own, tickets.view/tickets.approve_dev, planner.create, workflows.view, bots.view, and memory.view. Developers run sessions, approve their own implementations, and start plans, without admin or QA-approval rights.

A read-only stakeholder Create a Viewer role with only the *.view permissions (sessions.view_all, tickets.view, statistics.view, insights.view). Add a product manager to the relevant workspaces — they can follow progress and read dashboards but change nothing.

Grant a single extra capability A senior developer needs to bypass approvals for hotfixes. Rather than make them admin, grant just tickets.skip_to_merge (via their role or a direct grant). Effective permissions are the union of all their roles plus direct grants, so the one capability is added without over-provisioning.

Why someone can't see a workspace A user has tickets.manage but reports a workspace is missing. They hold the permission but aren't a member — add them under Workspace → Members. Permissions say what they can do; membership says where.

Permission cache

Permission lookups are cached briefly (about a minute) per user to avoid hot-path DB queries. After role or membership changes, the user may need up to a minute for the new permissions to take effect (or they can sign out and back in to flush).

Common pitfalls

• "Why can't I see this workspace?" — You hold the permission but aren't a member. Add yourself (or have an admin add you).
• "Why can't I approve QA?" — You're a member but lack tickets.approve_qa.
• "My new role isn't applying" — short permission cache; wait about a minute, or sign out and back in.
• "Admin sees everything by design" — Admin bypass is intentional. Use a less-privileged role if you need scoping.