Workflows: Manage users

Day-to-day operations on the Users page: list, create, edit, assign roles, and soft-archive.

Prerequisites

• A working connection. See Getting started.
• users:read to view the list. users:write to create, edit, archive, or assign roles. acaso_os:admin implicitly satisfies both.

If the active connection lacks both users:read and acaso_os:admin, the Users nav item is hidden. A direct visit to /users renders the "Insufficient permissions" empty state without issuing a request.

List users

Open /users. The page calls GET /v1/users and renders a paginated table with display name, email, kind, status, and role chips. Filters live in the URL via nuqs so the view is shareable.

Create a user

Click New user. The form:

Field	Required?	Notes
Display name	yes	Free text.
Email	yes for kind=person	Unique within the tenant.
Kind	yes	person or system. Finer labels go in metadata.subtype.
External id	no	Links the user to a customer-side identity.
Extra scopes	no	Per-user scopes that augment role scopes. Cannot be self-granted.

Submit calls POST /v1/users. The audit log records action = user.create attributed to the session key's parent.

Assign roles

Open the user's detail page. The Role Assignment widget calls POST /v1/users/{id}/roles for each picked role.

The assignment appears in the UI immediately. Within roughly 60 seconds the user's effective scopes (visible on the same page) reflect the role's scopes after the Redis cache TTL.

To remove a role, click the X on the role chip and confirm. The console calls DELETE /v1/users/{id}/roles/{role_slug}.

Edit a user

Inline-editable fields are display_name, email, external_id, and extra_scopes. Submit calls PATCH /v1/users/{id}. (kind is fixed at creation and is not editable.)

Note: A user can edit their own display_name and metadata without holding users:write. Self-grant of extra_scopes is rejected by the API with 403 and the console surfaces the error inline.

Soft-archive

Click Archive on a user detail page. The console calls DELETE /v1/users/{id}. The row's status flips to archived.

The user's roles and keys are unaffected; archive is purely a visibility and onboarding-state signal. To fully revoke access, also revoke their keys.

Reassigning a user's keys

A user can have multiple long-lived keys (for example after a key rotation). All of them inherit the user's roles and scopes. Archiving a user does NOT revoke their keys; the operator must explicitly revoke each.