Workflows: Manage roles

Create, edit, and delete roles, plus the catalog picker that drives the scope editor.

Prerequisites

• roles:read to view. roles:write to mutate. acaso_os:admin implicitly satisfies both.

List roles

Open /roles. The page calls GET /v1/roles and lists each role with its slug, name, scope count, assignee count, and is_default flag. Default roles (admin, member, viewer) are tagged.

Create a role

Click New role. The form requires:

Field	Description
Slug	URL handle, immutable. Lowercase letters, numbers, dashes.
Name	Display name.
Scopes	The initial scope set, picked via the editor below.

The scope editor has two sections.

Built-in scopes

Checkboxes pulled from GET /v1/scopes/catalog. Each entry is described inline. Template scopes such as agents:<name>:run reveal a sub-input where you supply the resource id.

Custom scopes

A free-form chips input where you type tenant-specific scopes such as team:engineering or project:atlas. The console syntax-validates each entry (lowercase, segment-wise, no bare *).

Submit calls POST /v1/roles.

Edit a role

Click a role to open its detail page. The Edit button toggles the same scope editor in mutate mode. Changes go through PATCH /v1/roles/{slug}.

After save, the backend publishes role.update <role_id> on acaso:key:invalidated. Replicas drop their cached entries for affected users within the cache TTL (roughly 60 seconds). The console refetches /v1/users/me automatically when the active operator's roles change.

Tip: Concurrent edits are last-write-wins in v1. If another operator's updated_at advanced between your fetch and save, a warning toast surfaces; reload the role and reapply.

Delete a role

Click Delete. Two server-side guards apply:

• is_default = true. Default roles cannot be deleted. The console renders a confirmation modal that blocks the action; the backend returns 409 if asked anyway.
• Assigned users. A role with assigned users returns 409 with a list of the affected user ids. The console displays the list and offers "Unassign all and retry" or "Cancel".

The audit log records action = role.delete on success.

Audit a role's history

The detail page has a Users tab calling GET /v1/roles/{slug}/users to list every user currently bound to the role. Use this before deleting a role to confirm impact.