Roles and permissions
Polyant authorizes every management-API request against a permission, not against a role name. Roles are named bundles of permissions; the permission is what the route declares and what the guard checks.
This page is the reference for the permission taxonomy, the four system roles and their exact grants, how a decision is resolved, and how custom roles and API keys fit in.
The permission taxonomy
A permission is resource:action. Agent-scoped resources are namespaced under agent.:
| Permission | Covers |
|---|---|
agent:read / agent:write / agent:delete | An agent’s identity and lifecycle |
agent.prompt:read / agent.prompt:write | Prompt sections |
agent.tool:read / agent.tool:write | Enabled tools, and the hook-function catalogue |
agent.skill:read / agent.skill:write | Skill assignments, pins, and skill env |
agent.knowledge:read / agent.knowledge:write | Knowledge documents, including its export/import |
agent.channel:read / agent.channel:write | Channel configuration |
agent.room:read / agent.room:write | Room configuration and event sources |
agent.task:read / agent.task:write | Scheduled tasks |
agent.secret:read / agent.secret:write | The agent’s encrypted secrets |
agent.governance:read / agent.governance:write | Governance, compliance, hooks, and opt-out |
agent.export:read | The full configuration export |
conversation:read / conversation:delete | Conversations, their state, and retention |
memory:read / memory:write | The memory store |
analytics:read | Analytics and the activity stream |
skill.catalog:read / skill.catalog:write | The global skill catalogue |
org:read / org:write | Organization settings, custom roles, API keys |
org.member:manage | Membership, workspaces, invitations |
audit_log:read | Audit logs, including the authorization audit |
The REST API reference lists the permission each route requires.
Two grants are deliberately stronger than they look:
agent.secret:readis admin-grade even though it is a read: the API returns which secrets are configured, and secret key names are themselves sensitive.agent.export:readis admin-grade for the same reason — a configuration export enumerates the agent’s secret key names.
The four system roles
| Role | Level | In one line |
|---|---|---|
| Owner | 40 | Everything, including organization settings |
| Admin | 30 | Everything operational, including secrets, deletes, and membership |
| Member | 20 | Builds and runs agents; no secrets, no deletes, no membership |
| Viewer | 10 | Read-only, secrets excluded |
The level is a hierarchy used to prevent privilege escalation, not an extra permission.
The grants are strictly nested — each role holds everything the role below it holds, plus its own additions:
| Role | Adds on top of the role below |
|---|---|
| Viewer | agent:read, agent.prompt:read, agent.tool:read, agent.skill:read, agent.knowledge:read, agent.channel:read, agent.room:read, agent.task:read, agent.governance:read, conversation:read, memory:read, analytics:read, skill.catalog:read, org:read |
| Member | agent:write, agent.prompt:write, agent.tool:write, agent.skill:write, agent.knowledge:write, agent.channel:write, agent.room:write, agent.task:write, memory:write |
| Admin | agent:delete, agent.secret:read, agent.secret:write, agent.export:read, agent.governance:write, conversation:delete, skill.catalog:write, org.member:manage, audit_log:read |
| Owner | org:write |
Two consequences worth reading twice:
- A Viewer cannot see secrets at all — not even which keys are configured. That is deliberate, not an oversight in the read tier.
- A Member can change what an agent does (prompts, tools, skills, channels, knowledge) but cannot see or set its credentials, cannot delete anything, and cannot change governance policy.
How a decision is made
For a request against an agent, in order:
- Platform Superadmin bypass. A platform superadmin is allowed, ahead of any role resolution. This is a platform-level flag on the user, not an organization role — see Authentication.
- Workspace binding, if one exists for the agent’s workspace. It is authoritative: it both grants permissions the organization baseline lacks and revokes ones the baseline grants. Most-specific-wins, in both directions. Workspace-scoped bindings are an enterprise feature.
- Organization binding, otherwise.
- Deny. No applicable binding means no access — empty is deny, everywhere.
Because a workspace binding replaces rather than adds to the org baseline, giving someone a Viewer binding on one workspace is how you narrow an org-wide Admin down for that workspace.
Bindings are cached briefly for the hot path. A membership change flushes the acting user’s cache immediately, so a role assignment takes effect on the very next request. A permission change to a custom role self-heals within the cache TTL instead.
Two guards protect against lock-out and escalation on every membership mutation:
- Owner-last. An organization can never be left without an Owner, whether by demoting or by removing its only one.
- No self-escalation. An operator cannot grant a role above their own level, nor modify a member who already outranks them.
Custom roles (Enterprise)
Enterprise feature. Available on Polyant Enterprise deployments.
An organization can define its own roles: a key, a display name, a level (0–100), and any subset of the permission taxonomy above. Custom roles are per-organization and are resolved exactly like system roles — the resolution rules are unchanged, only the set of available roles grows.
System roles are immutable, and a custom role can never take a system role’s key. See Roles (admin panel).
Management API keys
A management API key authenticates as a service principal rather than a user: it is org-scoped and carries an explicit permission set. It never gets the superadmin bypass.
Without the enterprise granular-key feature, a key carries the full Owner permission set. With it, a key can be restricted to any subset of that set — never more. See API keys.
Local account roles are a different axis
The users table also carries a local role (superadmin / user) used by the platform-level account administration API under Settings → Users. That axis governs who can administer sign-in accounts; the roles on this page govern what an operator can do inside an organization. Do not conflate the two. See Users.
See also
- Members — assigning organization roles.
- Workspaces — workspace-scoped bindings.
- Roles — the custom-role editor.
- API keys — service principals.
- Authorization audit — the trail of role and membership changes.
- REST API reference — per-route permissions.