Roles

Managed services. Custom roles are available with Polyant managed services.

Roles is the second tab of Members and roles, in Settings → Organization (/organizations/{org}/settings/organization/people). It defines roles beyond the four built-in ones, scoped to the organization. The tab requires org:write - Owner only - and the whole surface is refused on a deployment without the custom-roles feature.

It is gated on the tab, not on the section: its neighbour needs only org.member:manage and no entitlement, so one shared gate would have shut out one of the two audiences whichever way it was set.

The four system roles (Owner, Admin, Member, Viewer) are always present and always immutable. Custom roles do not replace them: they add to the set of roles that Members can be bound to, and they resolve by exactly the same rules.

Creating a role

• Key - the stable identifier, lowercase, starting with a letter, alphanumerics plus - and _, up to 50 characters. It is immutable after creation, and it can never be one of the reserved system keys (owner, admin, member, viewer).
• Name - the display name, up to 100 characters.
• Level - an integer from 0 up to your own level, defaulting to 0. The level is the anti-escalation hierarchy, not an extra permission: it decides who may grant this role and whom its holders may manage. System levels are Owner 40, Admin 30, Member 20, Viewer 10 - and since this screen needs org:write, an Owner is the one editing it and 40 is the ceiling. Only a platform admin is exempt.
• Permissions - any non-empty subset of the permission catalogue, chosen in the permission matrix. An unknown or mistyped key is rejected rather than silently dropped.

The catalogue offered is the full taxonomy, including org:write, org.member:manage, workspace:write, workspace.member:manage and workspace.assignment:manage. The ceiling is the same rule that governs API keys - you may only put in a role what you already hold - but expressed against your own effective permissions rather than a fixed Owner matrix. For an Owner the two coincide, so an Owner can define a role as powerful as an Owner; a custom role holding org:write without, say, org.secret:write cannot pass on what it lacks. Review levels and permissions together.

The taxonomy is deliberately fine-grained enough to express standings the four system roles cannot. Workspace structure, workspace placement, and organization membership are three separate keys, and the organization’s provider connections, its policy catalogue, and its authorization audit each have their own org-tier key - so “may create workspaces but administers nobody”, or “may read the audit trail and nothing else”, are both expressible.

A custom role whose holders should test agents from the panel needs agent.playground:use, which the Playground and the agent page’s test chat require; agent:read alone shows the Playground but cannot send a message. The upgrade to 1.2.0 added the permission to every custom role that held agent:write at the time. Any other custom role needs it ticked here.

A key that already exists in the organization returns a conflict.

Editing and deleting

Name, level, and permissions are editable; the key is not. Targeting a system role, a role from another organization, or a non-existent id all answer the same way - not found - so the screen cannot be used to probe another tenant.

Deleting a role removes it; bindings that referenced it stop granting anything, which is a real permission change for the people who held it.

When a change takes effect

A binding change (assigning a user a different role) flushes that user’s cached permissions immediately.

A permission change to a role is different: it alters the effective grant of everyone bound to it, and the caches self-heal within their short TTL instead of being flushed org-wide. Expect up to a cache window before a widened or narrowed role is enforced everywhere - plan a revocation accordingly rather than assuming it is instant.

Every create, update, and delete is recorded in the authorization audit.

See also

• Roles and permissions - the taxonomy and the resolution order.
• Members and roles - binding a role to a user; this screen’s other tab.
• Workspaces - binding a role to a workspace.