Permissions
Polygent authorization combines role permissions (what a user can do), workspace membership (where they can do it), ownership rules, and an administrator bypass.
Access model
A permission answers what a user can do; workspace membership answers where.
For workspace-scoped data, a non-administrator needs both the relevant permission and membership in the workspace. Ownership-sensitive features distinguish the user's own records (sessions, automations, plans) from everyone's. The UI hides unavailable actions, but the server is authoritative and rejects unauthorized requests.
| Control | Effect |
|---|---|
| Role permissions | Grant capabilities; permissions from multiple assigned roles are combined. |
| Workspace membership | Limits visible and actionable workspace data. |
| Own versus all permissions | Limits access to records the user owns unless broader access is granted. |
| Administrator | Bypasses permission and workspace checks. Round tables remain private to their creator even for administrators. |
The first user to sign in becomes an administrator. Protect that account, assign at least one additional trusted administrator, and use non-administrator accounts for routine work. The last active administrator cannot be blocked, deleted, or demoted.
Permission reference
This is the complete permission list as shown in the role editor, grouped by category.
| Category | Permission | Grants |
|---|---|---|
| Admin | Administrator | Full access; bypasses all other checks. |
| Users | View Users | View users and roles. |
| Manage Users | Create, edit, block, and delete users; manage roles; Settings → Active Sessions. | |
| Sessions | View Own Sessions | View sessions the user owns. |
| View All Sessions | View every session in the user's workspaces. | |
| Create Sessions | Create sessions. | |
| Allow to create new Chat session | Start Chat sessions. | |
| Allow to create new Develop session | Start Develop sessions. | |
| Edit Sessions | Edit session details and settings. | |
| Delete Sessions | Delete sessions. | |
| Manage All Sessions | Act on other users' sessions. | |
| Merge to Starter | Merge a session branch into its starting branch. | |
| Workspaces | View Workspaces | View workspaces the user belongs to. |
| Create Workspaces | Create workspaces. | |
| Edit Workspaces | Edit workspace settings, including budgets, capability ceiling, ticket configuration, and deploy templates. | |
| Delete Workspaces | Delete workspaces. | |
| Manage Workspace Users | Add and remove workspace members. | |
| Hosts | View Hosts | View hosts, slots, and deployments. |
| Manage Hosts | Approve and configure hosts; manage slots and run deployments; Hosts settings. | |
| Manage Host API Keys | Create, rotate, revoke, and delete worker credentials. | |
| Workflows | View Workflows / Manage Workflows | View, or create, edit, and delete workflows. |
| Settings | View Settings / Manage Settings | View, or change, application settings, models and backends, Bash policy, branding, and license. |
| PolygentCode | Manage PolygentCode User Settings | Change the harness User Settings. |
| Bots | View Bots / Manage Bots | View, or create, edit, and delete bots and categories. |
| Subagents | View Subagents / Manage Subagents | View, or manage, subagents. |
| Skills | View Skills / Manage Skills | View, or manage, skills. |
| Insights | View Insights / Manage Insights | View, or dismiss, regenerate, and link, insights. |
| Automations | View Own Automations / View All Automations | View the user's own, or all, automations. |
| Manage Automations / Manage All Automations | Create and manage the user's own, or any, automations. | |
| Planner | Create Plans | Start plans. |
| View All Plans | Open other users' plans read-only. | |
| Manage Plans | View, edit, and cancel other users' plans. | |
| Statistics | View Statistics | Open the Statistics dashboard. |
| Merge Conflicts | View Merge Conflicts / Manage Merge Conflicts | View, or resolve, retry, and cancel, merge requests. |
| Tickets | View Tickets | View tickets. |
| Manage Tickets | Create, edit, queue, cancel, and delete tickets; retry failed Plans. | |
| Approve Developer | Perform Developer Approval and approve Plans. | |
| Approve QA | Perform QA Approval. | |
| Merge to Starter (Tickets) | Skip to Merge: bypass approvals and deliver a ticket directly. | |
| Memory | View Memory / Manage Memory | View, or manage, memory stores and items. |
| RoundTables | New Round Table | Create round tables. |
| Manage Personas | Manage personas and enable them per workspace. | |
| MCPs | View MCP Servers / Manage MCP Servers | View, or manage and connect, external MCP servers. |
Two permissions are labeled Merge to Starter: the one under Sessions merges a session branch; the one under Tickets is the Skip to Merge action. Some capabilities also depend on license features and the state of the target record — a permission grants eligibility; it does not override a disabled feature, an invalid state transition, repository protection, or external-provider access.
Manage roles
Roles are reusable permission bundles managed with the users.
- Open Settings → Users → Roles with Manage Users.
- Create a role with a purpose-specific name.
- Select only the permissions required for that job function.
- Assign one or more roles to each user on the Users tab.
- Add non-administrators to the workspaces they need.
- Test with a non-administrator account before broad rollout.
A role cannot be deleted while assigned to users, and the built-in Admin role cannot be deleted. Role changes apply to every assigned user, so review membership before expanding a shared role.
Promoting a user to administrator removes their explicit workspace memberships (administrators see every workspace). Demoting an administrator adds them to every workspace — remove the memberships they should not keep immediately afterward.
Manage workspace membership
Workspace membership is the tenant boundary for non-administrators.
Open the workspace's Users tab (visible with Manage Workspace Users) and add or remove users. A new workspace has no members; its creator must be added unless they are an administrator. Removing membership hides the workspace's resources but does not delete the user's account, roles, authored records, or history.
Administrators see every workspace without membership. Do not grant Administrator to solve a missing-membership issue; add the user to the workspace instead.
Recommended role baseline
Start with narrow roles and add capabilities only when a verified workflow requires them.
| Role | Recommended permissions |
|---|---|
| Supporter | View Users, View Workspaces, View All Sessions, View Tickets, View Hosts, View Statistics, View Insights, View Merge Conflicts, View Settings. |
| Developer | Create Sessions, Allow to create new Chat/Develop session, View Own Sessions, Edit Sessions, View Tickets, Approve Developer, Merge to Starter (Sessions). |
| QA reviewer | View All Sessions, View Tickets, Approve QA, View Statistics. |
| Deployment operator | View Hosts, Manage Hosts; add Manage Host API Keys only when credential rotation is part of the role. Edit Workspaces is needed to change deploy templates. |
| Security administrator | Manage Users, Manage Settings, Manage Host API Keys; avoid routine development permissions where separation of duties is required. |
| Read-only stakeholder | View-only permissions for the required modules, plus workspace membership. |
The matrix has no wildcard permissions. Review new permissions after every upgrade; existing custom roles do not automatically include newly added capabilities.
Security operations
Authorization changes are security-sensitive configuration.
- Keep Administrator, Manage Users, Manage Settings, Manage Host API Keys, Merge to Starter (Tickets), and Manage Hosts narrowly assigned.
- Separate credential management from day-to-day worker or slot operation where possible.
- During offboarding, block the user (this also frees their license seat), then remove roles and workspace memberships. Users who own records cannot be deleted; blocking preserves history.
- Revoke devices and external personal access tokens separately; role removal alone does not revoke every credential.
- Periodically review role membership against current job responsibilities.
- Test denial as well as success: confirm a user cannot see unrelated workspaces or perform destructive actions.
Troubleshooting
Resolve access problems by checking permission, membership, ownership, license, and target state, in that order.
| Symptom | Resolution |
|---|---|
| Workspace is missing | Add the non-administrator user on the workspace Users tab. |
| Creator cannot see a new workspace | Workspaces start without members; add the creator. |
| Action is hidden or access is denied | Grant the exact permission through an assigned role and confirm workspace membership. |
| User can view only some sessions | Grant View All Sessions if justified; View Own Sessions intentionally limits scope. |
| User cannot manage another user's automation or session | Grant Manage All Automations or Manage All Sessions rather than Administrator. |
| Role cannot be deleted | Remove it from all users; the built-in Admin role cannot be deleted. |
| User cannot be deleted | The user owns records; block the user instead. |
| Former administrator has access to every workspace | Demotion adds all memberships; remove the unwanted ones. |
| Permission appears correct but feature is absent | Check the installed license and whether the feature is enabled and configured. |
| Administrator cannot open a round table | Expected; round tables are private to their creator. |
| User retained an external capability after offboarding | Revoke identity-provider sessions, personal access tokens, host keys, and repository/provider credentials separately. |