Users & Roles

RondoFlow runs as a single shared team workspace. Every authenticated user operates on the same pool of Assistants (agents), Safety Rules (policies), Connections (MCP), and Conversations (sessions) — there is no per-user data. What a user can do with that shared pool is controlled by their global role.

There are three roles, and access is invite-only: open self-registration is disabled, so a new account exists only because an admin created it.

The three roles

Roles are ranked and additive — viewer < editor < admin. Each role inherits everything the role below it can do and adds more.

The capability matrix is the single source of truth for what each role unlocks: read requires viewer, write and run require editor, and manageUsers and manageGlobalSettings require admin.

New accounts default to viewer (DEFAULT_USER_ROLE), a fail-closed choice: an unrecognized or missing role collapses to viewer rather than to something more permissive.

Getting in: the first admin

Because self-registration is disabled, you cannot create your own account from the login page — it reads “Access is invite-only. Ask an administrator to create your account.” So the very first admin has to be bootstrapped at seed time.

Set these environment variables before seeding:

The bootstrap is idempotent and fail-safe: it is skipped if either the email or password is blank, and if the user already exists it simply ensures their role is admin (it does not overwrite anything else, including the name). The seed creates the account with a hashed credential, so the bootstrapped admin can log in with email and password immediately.

Sign-in methods

Email/password and GitHub/Google OAuth all remain valid ways to sign in — only sign-up is disabled. OAuth providers are configured to never self-provision: they can only sign in a user an admin has already created. They will never create a new account on the fly.

A social provider button only appears on the login page when that provider is actually configured. Each provider is enabled only when its OAuth client ID is set (GITHUB_CLIENT_ID / GOOGLE_CLIENT_ID), and the login page reads a booleans-only endpoint (/api/auth-providers) to decide which buttons to render — a provider with no client ID is hidden, and no credential values are ever exposed. See OAuth sign-in.

Managing users (admins)

Admins manage everyone from the Users panel in the UI: invite/create a user with a starting role, change a role, deactivate/reactivate, and delete. Each of these actions is also available via the API under /api/users. Every route requires the admin role, uses the standard { success, data?, error?, meta? } envelope, and is recorded to the audit log.

A user row has the shape { id, email, name, image, role, banned, createdAt }.

Each admin action writes an entry to the audit log — user_invited, user_role_changed, user_deactivated, user_reactivated, and user_deleted — so user-management changes are reviewable later. See Monitoring & Audit.

Examples

These use cookie auth: sign in first and persist the session cookie with -b cookies.txt -c cookies.txt.

curl -X POST http://localhost:3001/api/users \
  -b cookies.txt -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alex@example.com",
    "name": "Alex Rivera",
    "password": "a-strong-password",
    "role": "editor"
  }'

curl -X PATCH http://localhost:3001/api/users/USER_ID/role \
  -b cookies.txt -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{ "role": "admin" }'

How enforcement works

The server is the real security boundary. UI affordances — a hidden palette, disabled buttons — are advisory only; the checks that matter all live server-side and fail closed.

REST is a default-deny gate keyed on HTTP method + path. Two preHandler hooks run on every request:

Because the fallthrough rule covers all other mutations, a newly added mutating route is protected automatically — it fails safe.

Socket.IO is gated too. Viewers are read-only over the socket: an editor-or-above check guards chain execute/stop, agent start/stop/message, Discussion start, Director and approval responses, Loops, and the Advisor. Viewers attempting any of these are denied with a policy error (for example, the Advisor returns “Your role does not permit running analysis”).

In the UI, a role badge appears in the user menu, the admin-only Users panel is shown to admins, and viewers get a read-only Canvas — the palette is hidden and nodes are not draggable, connectable, or deletable. These mirror the server’s capabilities (and default to viewer until the session resolves), but they are convenience only; the server is what enforces access.

Related