Roles

Enterprise feature. Custom roles are available on Polyant Enterprise deployments.

The Roles screen (/roles) defines roles beyond the four built-in ones, scoped to the organization. It requires org:write — Owner only — and the whole surface is refused on a deployment without the custom-roles feature.

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 0–100, 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 — pick a level that places your role sensibly among them.
• 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 and org.member:manage. There is no hidden ceiling here as there is for API keys — a custom role can be defined as powerful as an Owner, so review levels and permissions together.

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 — binding a role to a user.
• Workspaces — binding a role to a workspace.